|
|
| (7 intermediate revisions by 3 users not shown) |
| Line 1: |
Line 1: |
| {{admon/warning|This page is a DRAFT and is currently under development}} | | {{admon/warning|This page is a DRAFT and is currently under development. [https://fedorahosted.org/fpc/ticket/506 FPC ticket 506]}} |
| | == Services which may be enabled by Default == |
| | Only services that meet the criteria below are permitted to be enabled by default on package installation. |
|
| |
|
| = First-time Service Setup =
| | For the purposes of this document, a "service" is defined as one or more of: |
| Many system services require some amount of initial setup before they can run properly for the first time. Common examples are the generation of private keys and certificates or a unique, system-specific identifier.
| | * A daemon or process started using a [http://www.freedesktop.org/software/systemd/man/systemd.service.html systemd service unit]. |
| | * A daemon or process that is invoked by socket activation, either by using a [http://www.freedesktop.org/software/systemd/man/systemd.socket.html systemd socket unit], [http://standards.freedesktop.org/desktop-entry-spec/1.1/ar01s07.html D-BUS activation] or similar behavior. |
| | * A [http://www.freedesktop.org/software/systemd/man/systemd.timer.html systemd timer unit] that runs periodically. |
|
| |
|
| Traditionally, this was done by RPM scriptlets as part of the installation or upgrade of a package. This was sensible for a time when the majority of installations were performed by attended or unattended installers (such as anaconda and kickstart).
| | === Locally running services === |
| | If a service does not require manual configuration to be functional and does not listen on a network socket for connections originating on a separate physical or virtual machine, it may be enabled by default (but is not required to do so). |
|
| |
|
| Today we see an increased reliance on generating virtual machine images for use in both traditional and cloud-computing environments. In those cases, having system-specific data created at package installation time is problematic. It means that the production of such images need to have significant care applied to remove any system-specific information about them and then additional tools written to apply the corrected information post-deployment. '''The goal of this guideline is to ensure that if a system clean-up service such as virt-sysprep is run on the system and then the machine is rebooted, any service that requires first-time configuration will re-run it.''' The mechanism by which we will accomplish this is to remove such first-time configuration from RPM scriptlets (e.g. <code>%post</code>) and instead execute this configuration as part of service startup with systemd.
| | Example: Local D-BUS services |
|
| |
|
| This guideline describes a mechanism that can be used for both traditional and cloud-based deployment styles.
| | === Non-persistent services === |
| | In addition, any service which does not remain persistent on the system (aka, it "runs once then goes away"), does not listen to incoming connections during initialization, and does not require configuration to be functional may be enabled by default (but is not required to do so). |
|
| |
|
| Note: this requirement can be waived if the equivalent functionality is incorporated as part of the service's own standard startup. These guidelines are meant to address services that require setup before the service can be started.
| | Example: iptables |
|
| |
|
| == Defining System-Specific Setup == | | === Approved Exceptions === |
| A particular setup task is defined thusly: "Any action that must be performed on the system where the service will be run whose output is not identical for all systems running that service."
| |
|
| |
|
| Some non-exhaustive examples of system-specific configuration: | | Some services which are permitted to be enabled by default as specific exceptions. Services that should be enabled by default throughout all of Fedora must be approved by [https://fedorahosted.org/fesco/newticket FESCo]. Services that should be enabled or disabled by default only on one or more of the Fedora Editions must be approved by those Editions' [https://fedoraproject.org/wiki/Fedora.next#Working_groups Working Groups]. |
| * The SSH daemon generates a public/private host key
| |
| * The mod_ssl httpd module creates a self-signed certificate for the machine's hostname
| |
| * A remote logging service creates a UUID to represent this machine
| |
|
| |
|
| A few examples that should '''not''' be considered system-specific configuration:
| | Example: |
| * Creating a service user and/or group. This is safe to copy to clones of the system. | | * FESCo approves openssh-server to run by default on Fedora in general. |
| * Any content that is automatically re-generated by the service upon deletion. | | * Workstation WG approves openssh-server to be disabled by default on the Workstation Edition. |
|
| |
|
| == Common Guidelines ==
| |
| For all system-specific cases, we will take advantage of systemd's [http://www.freedesktop.org/software/systemd/man/systemd.service.html service] functionality. Packagers will create a new service unit file for each service unit in their package that requires per-system configuration. This service unit will be named <code><servicename>-init.service</code> and installed to <code>/usr/lib/systemd/system</code>. For example, the <code>tog-pegasus.service</code> configuration unit would be <code>/usr/lib/systemd/tog-pegasus-init.service</code>.
| |
|
| |
|
| The contents of this service unit will be as follows:
| | == Current list of enabled/disabled services == |
| <pre>
| | * [https://pagure.io/fedora-release/blob/master/f/90-default.preset Fedora general] |
| [Unit] | | * [https://pagure.io/fedora-release/blob/master/f/80-server.preset Fedora Server] |
| Description=One-time configuration for <servicename>
| | * [https://pagure.io/fedora-release/blob/master/f/80-workstation.preset Fedora Workstation] |
|
| |
|
| ConditionPathExists=!/path/to/generated/config
| | == How to enable a service by default == |
| ConditionPathExists=|!/path/to/other/generated/config (one or more lines optional)
| |
|
| |
|
| [Service] | | Unit files must correspond to the Fedora Packaging [[Packaging:ScriptletSnippets#Systemd|Guidelines]]. Services are enabled or disabled by default through [http://www.freedesktop.org/software/systemd/man/systemd.preset.html systemd preset files]. Preset files can be overridden by a local administrator, but a set of defaults are provided by Fedora. |
| Type=oneshot
| |
| RemainAfterExit=no
| |
|
| |
|
| ExecStart=/path/to/config/script
| | If the service should be enabled by default, it must be added to one of the distribution presets files (see above). |
| </pre>
| |
|
| |
|
| The syntax for <code>ConditionPathExists=</code> uses the ! to indicate negation (the file is not present). The | is used to create an OR logical pairing (resulting in the lack of ANY of these files causing the configuration to be run). The <code>/path/to/config/script</code> can be any executable script or binary that will generate the initial configuration needed by this service. It '''must''' generate the files tested by <code>ConditionPathExists</code>. If the script is a single command, it can be run directly by this service unit. If it needs to run multiple commands, it is recommended to create a script file in the package's <code>/usr/libexec/<packagename></code> directory and execute that.
| | For services which meet one of the conditions listed above, a ticket should be filed against the |
| | | [https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=fedora-release&short_desc=PRESETS:+enable+...+by+default&version=rawhide fedora-release package]. If the preset should be changed for versions other than rawhide, indicate that in the ticket. |
| To use <code>tog-pegasus.service</code> as an example:
| |
| <pre>
| |
| [Unit]
| |
| Description=One-time configuration for <servicename>
| |
| | |
| ConditionPathExists=!/etc/Pegasus/server.pem
| |
| ConditionPathExists=|!/etc/Pegasus/file.pem
| |
| ConditionPathExists=|!/etc/Pegasus/client.pem
| |
| | |
| [Service]
| |
| Type=oneshot
| |
| RemainAfterExit=no
| |
| | |
| ExecStart=/usr/bin/sscg --package tog-pegasus --ca-file /etc/Pegasus/client.pem --cert-file /etc/Pegasus/server.pem --cert-key-file /etc/Pegasus/file.pem
| |
| </pre>
| |
| | |
| The <code>ExecStart</code> command may do anything, so long as it returns 0 on success. In this case, we are generating a self-signed certificate for the service to use.
| |
| | |
| Packagers will also need to update their primary service unit to require this one and run after it:
| |
| <pre>
| |
| [Unit]
| |
| ...
| |
| Requires=<service>-init.service
| |
| After=<service>-init.service
| |
| </pre>
| |
| | |
| To continue the <code>tog-pegasus.service</code> example:
| |
| <pre>
| |
| [Unit]
| |
| Description=OpenPegasus CIM Server
| |
| After=slpd.service
| |
| | |
| Requires=tog-pegasus-init.service
| |
| After=tog-pegasus-init.service
| |
| | |
| [Service]
| |
| Type=forking
| |
| ExecStart=/usr/sbin/cimserver
| |
| PIDFile=/var/run/tog-pegasus/cimserver.pid
| |
| | |
| [Install]
| |
| WantedBy=multi-user.target
| |
| </pre>
| |
| | |
| == Special Case: Self-signed Certificate Generation ==
| |
| If your service makes use of the SSL/TLS protocol for transport security, your service will require a service certificate. Ideally the administrator deploying a new service should obtain an X.509 certificate from an appropriate Certificate Authority (CA), which should be from a globally operating CA (such as a commercial SSL certificate vendor) if your service will be available on the public Internet, or from a private CA (such as a domain controller CA) if your service will run inside an Intranet. | |
| | |
| However, it is often desirable to start using a self-signed certificate, which can be immediately created, and allows the administrator to immediately proceed doing the installation tasks. This document will explain how to obtain a self-signed certificate, but it is recommended that it gets replaced prior to public deployment.
| |
| | |
| The disadvantage of self-signed certificates is that most client software (like web browsers) will reject them as untrusted, and if at all, will require the user to override and trust it explicitly. The way this can be done varies depending on the client software. It is easier to add a CA certificate to the system store and mark it as trusted.
| |
| | |
| Therefore, instead of creating a self-signed certificate, we will create a temporary CA certificate and use it to sign the certificate used by the service. Afterwards we will delete the private key of the CA certificate, which will remove the ability to use it to create additional certificates. Afterwards we can import the CA certificate as trusted into the local system certificate store, and consequently every local client software that respects the system CA store will accept the service certificate as trusted.
| |
| | |
| === Easy implementation with sscg ===
| |
| | |
| There is a simple tool in Fedora called sscg (Self-Signed Certificate Generator) that will create a certificate using the above mechanism for you. See the tog-pegasus example above for a simple invocation.
| |
| | |
| <pre>
| |
| usage: sscg [-h] [--debug] [--cert-format {PEM,ASN1}] [--lifetime LIFETIME]
| |
| [--key-strength {512,1024,2048,4096}]
| |
| [--hash-alg {md4,md5,ripemd160,sha,sha1,sha224,sha256,sha384,sha512,whirlpool}]
| |
| --package PACKAGE [--ca-file CA_FILE] --cert-file CERT_FILE
| |
| --cert-key-file CERT_KEY_FILE [--hostname HOSTNAME]
| |
| [--subject-alt-names SUBJECT_ALT_NAMES [SUBJECT_ALT_NAMES ...]]
| |
| [--country COUNTRY] [--state STATE] [--locality LOCALITY]
| |
| [--organization ORGANIZATION]
| |
| [--organizational-unit ORGANIZATIONAL_UNIT]
| |
| | |
| Generate a self-signed service certificate
| |
| | |
| optional arguments:
| |
| -h, --help show this help message and exit
| |
| --debug Enable logging of debug messages.
| |
| | |
| Output:
| |
| --cert-format {PEM,ASN1}
| |
| Certificate file format. Default=PEM
| |
| --lifetime LIFETIME Certificate lifetime (days). Default=3650 (10 years)
| |
| --key-strength {512,1024,2048,4096}
| |
| Strength of the certificate private keys in bits.
| |
| Default=2048
| |
| --hash-alg {md4,md5,ripemd160,sha,sha1,sha224,sha256,sha384,sha512,whirlpool}
| |
| Hashing algorithm to use for signing. Default=sha256
| |
| --package PACKAGE The name of the package needing a certificate
| |
| --ca-file CA_FILE Path where the public CA certificate will be stored.
| |
| Default: ca.crt in service certificate directory
| |
| --cert-file CERT_FILE
| |
| Path where the public service certificate will be
| |
| stored.
| |
| --cert-key-file CERT_KEY_FILE
| |
| Path where the private key of the service certificate
| |
| will be stored
| |
| | |
| Certificate Details:
| |
| --hostname HOSTNAME The valid hostname of the certificate. Must be an
| |
| FQDN. Default: system hostname
| |
| --subject-alt-names SUBJECT_ALT_NAMES [SUBJECT_ALT_NAMES ...]
| |
| One or more additional valid hostnames for the
| |
| certificate
| |
| --country COUNTRY Certificate DN: Country (C)
| |
| --state STATE Certificate DN: State (ST)
| |
| --locality LOCALITY Certificate DN: Locality (L)
| |
| --organization ORGANIZATION
| |
| Certificate DN: Organization (O)
| |
| --organizational-unit ORGANIZATIONAL_UNIT
| |
| Certificate DN: Organizational Unit (OU)
| |
| </pre>
| |
| | |
| === Do-it-yourself ===
| |
| [[Sgallagh:SelfSignedCertGuidelinesDraft|Guidelines for scripting openssl or nss]]
| |
