Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update procedure Registering a Host to RH Satellite #780

Merged
merged 1 commit into from
Nov 12, 2021
Merged

Update procedure Registering a Host to RH Satellite #780

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 75 additions & 48 deletions guides/doc-Managing_Hosts/topics/proc_registering-a-host.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,86 +39,113 @@ Optional: If the *Registration* feature is not enabled on your {SmartProxy}, ent

.Procedure
. Navigate to *Hosts* > *Register Host*.
. Optional: Select a different *Organization*.
. Optional: Select a different *Location*.
. Optional: From the *Host Group* list, select the host group to associate the hosts with.
Fields that inherit value from *Host group*: Operating System, Activation Key(s) and Lifecycle environment.
. From the *Operating System* list, select the operating system of hosts that you want to register.
. Optional: From the *{SmartProxy}* list, select the {SmartProxy} to register hosts through. You must select the internal {SmartProxy} if you do not want to use an external {SmartProxy}.
. Optional: *Insecure* - This makes the first call insecure, however, during this first call, hosts download the CA file from {Project}. Hosts will use this CA file to connect to {Project} with all future calls making them secure.
Fields that inherit value from *Host group*: *Operating system*, *Activation Keys* and *Lifecycle environment*.
. Optional: From the *{SmartProxy}* list, select the {SmartProxy} to register hosts through.
ifdef::satellite[]
Lennonka marked this conversation as resolved.
Show resolved Hide resolved
You must select the internal {SmartProxy} if you do not want to use an external {SmartProxy}.
Lennonka marked this conversation as resolved.
Show resolved Hide resolved
endif::[]
. Optional: From the *Operating system* list, select the operating system of hosts that you want to register.
ifndef::satellite[]
Specifying an operating system is required when you register machines without `subscription-manager`, such as Debian or Ubuntu.
endif::[]
. Optional: Select the *Insecure* option, if you want to make the first call insecure.
During this first call, hosts download the CA file from {Project}.
Hosts will use this CA file to connect to {Project} with all future calls making them secure.
+
It is recommended to avoid insecure calls.
+
If an attacker, located in the network between {Project} and a host, fetches the CA file from the first insecure call, the attacker will be able to access the content of the API calls to and from the registered host and the JSON Web Tokens (JWT).
Therefore, if you have chosen to deploy SSH keys during registration, the attacker will be able to access the host using the SSH key.
+

. From the *Setup REX* list, select whether you want to deploy {Project} SSH keys to hosts or not.
Instead, you can manually copy and install the CA file on each host before registering the host.
+
To do this, find where {Project} stores the CA file by navigating to *Administer* > *Settings* > *Authentication* and locating the value of the *SSL CA file* setting.
+
Copy the CA file to the `/etc/pki/ca-trust/source/anchors/` directory on hosts and enter the following commands:
+
[options="nowrap", subs="+quotes,attributes"]
----
# update-ca-trust enable
# update-ca-trust
----
+
Then register the hosts with a secure `curl` command, such as:
+
[options="nowrap", subs="+quotes,attributes"]
----
# curl -sS https://{foreman-example-com}/register ...
----
+
The following is an example of the `curl` command with the `--insecure` option:
+
If set to `Yes`, SSH keys will be installed on the registered host. The inherited value is based on the `host_registration_remote_execution` parameter.
It can be inherited e.g. from host group, operating system, organization. When overridden, the selected value will be stored on host parameter level.
[options="nowrap", subs="+quotes,attributes"]
----
# curl -sS --insecure https://{foreman-example-com}/register ...
----
Lennonka marked this conversation as resolved.
Show resolved Hide resolved
. Select the *Advanced* tab.
. From the *Setup REX* list, select whether you want to deploy {Project} SSH keys to hosts or not.
+
If set to `Yes`, public SSH keys will be installed on the registered host.
The inherited value is based on the `host_registration_remote_execution` parameter.
It can be inherited, for example from a host group, an operating system, or an organization.
When overridden, the selected value will be stored on host parameter level.

. From the *Setup Insights* list, select whether you want to install `insights-client` and register the hosts to Insights.
+
The Insights tool is available for Red Hat Enterprise Linux only. It has no effect on other operating systems.
The Insights tool is available for {RHEL} only.
It has no effect on other operating systems.
+
You must enable the following repositories on a registered machine:

* RHEL 6: `rhel-6-server-rpms`
* RHEL 7: `rhel-7-server-rpms`
* RHEL 8: `rhel-8-for-x86_64-appstream-rpms` (The `insights-client` package is installed by default on RHEL 8 except in environments whereby RHEL 8 was deployed with "Minimal Install" option)
* RHEL 8: `rhel-8-for-x86_64-appstream-rpms`
+
The `insights-client` package is installed by default on RHEL 8 except in environments whereby RHEL 8 was deployed with "Minimal Install" option.

. Optional: {Project} uses the JSON Web Tokens (JWT) for authentication.
. Optional: In the *Token lifetime (hours)* field, change the validity duration of the JSON Web Token (JWT) that {Project} uses for authentication.
The duration of this token defines how long the generated `curl` command works.
If you want to change the duration of the token, enter the required duration to the *Token lifetime (hours)* field. You can set the duration to 0 - 999 999 hours or unlimited.
You can set the duration to 0 - 999 999 hours or unlimited.
+
Note that {Project} uses the permissions of the user who generates the `curl` command for authorization of hosts.
Note that {Project} applies the permissions of the user who generates the `curl` command to authorization of hosts.
If the user loses or gains additional permissions, the permissions of the JWT change too.
Therefore, do not delete, block, or change permissions of the user during the token duration.
Also, the scope of JWT is limited to the registration endpoints only and cannot be used anywhere else.
. Optional: In the *Remote Execution Interface* field, enter a network interface that hosts must use for the SSH connection.
+
The scope of the JWTs is limited to the registration endpoints only and cannot be used anywhere else.
. Optional: In the *Remote Execution Interface* field, enter the identifier of a network interface that hosts must use for the SSH connection.
If you keep this field blank, {Project} uses the default network interface.
. Optional: *Install packages* - Install packages on the host when registered. Can be set by `host_packages` parameter
. Optional: In the *Install packages* field, list the packages (separated with spaces) that you want to install on the host upon registration.
This can be set by the `host_packages` parameter.
. Optional: Select the *Update packages* option to update all packages on the host upon registration.
This can be set by the `host_update_packages` parameter.

. Optional: *Update packages* - Update packages on the host when registered. Can be set by `host_update_packages` parameter
. Optional: *Repository* - A repository to be added before the registration is performed. For example, it can be useful to make the subscription-manager packages available for the purpose of the registration. For Red Hat family distributions, this should be the URL of the repository.
For example, http://rpm.example.com/.
. Optional: In the *Repository* field, enter a repository to be added before the registration is performed.
For example, it can be useful to make the `subscription-manager` package available for the purpose of the registration.
For Red Hat family distributions, enter the URL of the repository, for example `\http://rpm.example.com/`.
ifndef::satellite[]
For Debian OS families, it's the whole list file content, for example 'deb http://deb.example.com/ buster 1.0'.
For Debian OS families, enter the whole line of list file content, for example `deb \http://deb.example.com/ buster 1.0`.
endif::[]
. Optional: *Repository GPG key URL* - If packages are GPG signed, the public key can be specified here to verify the packages signatures. It needs to be specified in the ascii form with the GPG public key header.
. Optional: In the *Repository GPG key URL* field, specify the public key to verify the signatures of GPG-signed packages.
It needs to be specified in the ASCII form with the GPG public key header.

ifdef::satellite,orcharhino[]
. In the *Activation Key(s)* field, enter one or more activation keys to assign to hosts.
. Optional: *Lifecycle environment*
. Optional: *Ignore errors* - Ignore subscription manager errors
. Optional: *Force* - Remove any `katello-ca-consumer` rpms before registration and run subscription-manager with --force argument.
. In the *Activation Keys* field, enter one or more activation keys to assign to hosts.
. Optional: Select the *Lifecycle environment*.
. Optional: Select the *Ignore errors* option if you want to ignore subscription manager errors.
. Optional: Select the *Force* option if you want to remove any `katello-ca-consumer` rpms before registration and run `subscription-manager` with the `--force` argument.
endif::[]

ifdef::foreman-el,foreman-deb,katello[]
. Optional: This step is for the Katello users only.
If you register RHEL or CentOS hosts, in the *Activation Key(s)* field, enter one or more activation keys to assign to registered hosts.
If you register RHEL or CentOS hosts, in the *Activation Keys* field, enter one or more activation keys to assign to registered hosts.
endif::[]

. Click *Generate command*.
. Copy the generated `curl` command to enter it on the hosts.
+
The following is an example of the `curl` command with the `--insecure` option:
+
[options="nowrap", subs="+quotes,attributes"]
----
curl -sS --insecure https://{foreman-example-com}/register...
----
+
If you do not want to call the `curl` command with the `--insecure` option, you can manually copy and install the CA file on each host.
+
To do this find where {Project} stores the CA file by navigating to *Administer* > *Settings* > *Authentication* and locating the value for the *SSL CA file* setting.
+
Copy the CA file to the `/etc/pki/ca-trust/source/anchors/` directory on hosts and enter the following commands:
+
[options="nowrap", subs="+quotes,attributes"]
----
# update-ca-trust enable
# update-ca-trust
----
. On the hosts that you want to register, enter the `curl` command as `root`.
. Click the *Generate* button.
Lennonka marked this conversation as resolved.
Show resolved Hide resolved
. Copy the generated `curl` command.
. On the hosts that you want to register, run the `curl` command as `root`.

ifdef::katello,satellite,orcharhino[]
[NOTE]
Expand Down