search

rockstor / rockstor-doc

Rockstor documentation
http://rockstor.com/docs
Other
25 stars 30 forks source link

Instructions on setting an install's Appliance ID #486

Closed phillxnet closed 1 month ago

phillxnet commented 2 months ago

On first start of 'rockstor' rpm associated systemd services a fake UUID check is carried out. Some motherboard/appliance manufacturers fail to honour the second 'U' in UUID which leaves us always playing catch-up with our curated list of fake UUID's.

When our fake (non-unique) Appliance ID check recognises repeat UUIDs we fail-over to generating an install specific UUID. But we do not do this by default as it is only install-specific; requiring Appliance ID edits on every re-install even on the exact same hardware. And give the vast majority of UUIDs are actually unique our current setup is more convenient for the majority of Rockstor installers. I.e. re-installs on the same motherboard (UUID originator) requires no Appman interactions to transit a Stable Updates subscription activation code (linked to Appliance ID).

It is proposed that we have a step-by-step doc section for those who already have an install with a fake UUID, with instruction on how-to change their install's Appliance ID. These same instructions may also be of interest to those how wish to define their own Appliance ID: for whatever reason. It may also serve as a reference for OEM/VAR/pre-installers regarding preparing systems in a more efficient manner.

Resources for proposed doc:

phillxnet commented 1 month ago

Notes

The point within our OEM orientated installer that instantiates the initial Appliance ID:

An install instance, at this stage, will have adapted to the target disk size and downloaded, from PyPi, and build the required Python environment (via rockstor-build systemd service); but has yet to establish its initial Appliance ID: usually derived directly from cat /sys/class/dmi/id/product_uuid: unless the output is among a known set of non-unique product_uuid's.

At this stage it is safe to shutdown/halt the possibly donor install hardware. The Web-UI setup stage will remain 'pending' and the system disk can be attached to the intended client host system/motherboard, so that the resulting Appliance ID (created during the initial Web-UI setup stage) will reflect the later system/motherboard Appliance ID.

Examining DB Appliance ID table contents:

N.B. our Postgres follows upstream defaults re localhost only access restrictions.

DB login (localhost 'root' user only)

psql -U rocky storageadmin
Password for user rocky:
psql (13.14)
Type "help" for help.

storageadmin=#

Appliance table nature:

storageadmin=# \d storageadmin_appliance
                                 Table "public.storageadmin_appliance"
      Column       |          Type           | Collation | Nullable |             Default              
-------------------+-------------------------+-----------+----------+----------------------------------
 id                | integer                 |           | not null | generated by default as identity
 uuid              | character varying(64)   |           | not null | 
 ip                | character varying(4096) |           | not null | 
 current_appliance | boolean                 |           | not null | 
 hostname          | character varying(128)  |           | not null | 
 mgmt_port         | integer                 |           | not null | 
 client_id         | character varying(100)  |           |          | 
 client_secret     | character varying(255)  |           |          | 
Indexes:
    "storageadmin_appliance_pkey" PRIMARY KEY, btree (id)
    "storageadmin_appliance_ip_4cc3c2c8_like" btree (ip varchar_pattern_ops)
    "storageadmin_appliance_ip_key" UNIQUE CONSTRAINT, btree (ip)
    "storageadmin_appliance_uuid_cfb52664_like" btree (uuid varchar_pattern_ops)
    "storageadmin_appliance_uuid_key" UNIQUE CONSTRAINT, btree (uuid)
Referenced by:
    TABLE "storageadmin_updatesubscription" CONSTRAINT "storageadmin_updates_appliance_id_00311ac8_fk_storagead" FOREIGN KEY (appliance_id) REFERENCES storageadmin_appliance(id) DEFERRABLE INITIALLY DEFERRED

Table contents BEFORE completing the Web-UI setup install step:

storageadmin=# SELECT * FROM storageadmin_appliance;
 id | uuid | ip | current_appliance | hostname | mgmt_port | client_id | client_secret 
----+------+----+-------------------+----------+-----------+-----------+---------------
(0 rows)

Table contents AFTER completing the initial Web-UI setup install step:

storageadmin=# SELECT * FROM storageadmin_appliance;
 id |                 uuid                 | ip | current_appliance | hostname  | mgmt_port | client_id | client_secret 
----+--------------------------------------+----+-------------------+-----------+-----------+-----------+---------------
  1 | 67bdf5bd-2c16-41d7-8224-ca864f2c0a68 |    | t                 | installer |       443 |           | 
(1 row)

Exit DB interactive CLI terminal via:

\q

On the same system we see the origin command output of this Appliance ID:

installer:~ # cat /sys/class/dmi/id/product_uuid
67bdf5bd-2c16-41d7-8224-ca864f2c0a68
phillxnet commented 1 month ago

Enforcing an Appliance ID post Web-UI setup.

The Appliance ID, as per the last comment's exposition, is an exact match to the output of the following command:

cat /sys/class/dmi/id/product_uuid

If the host motherboard manufacturer has failed to honour the second u in uuid, and the bundled version of the Rockstor package in a given installer is, as-yet, unaware of this known-fake uuid, a work-around it required: primarily to re-assert the assumed-by-Rocktor sub-systems (e.g. replication / Stable Updates subscription / future GlusterFS intergration) uniqueness.

Set a real UUID

One can trivially generate a UUID from a chosen genuine source: e.g. by visiting: https://www.uuidgenerator.net/

Substitute the generated UUID in the following command sequence: As the root user in local console of post Web-UI setup install where a non-unique Appliance ID has been confirmed.

psql -U rocky storageadmin
UPDATE storageadmin_appliance SET uuid='your-generated-appliance-id-here' WHERE current_appliance=True;
\q
exit

The above will ask for the hardwired password of 'rocky'.

Confirm the above override via the Rockstor's Web-UI via System -> Appliances.

system_appliances_page

Our doc should stress the ramifications of this change.