1subscription-manager(8) Subscription Management subscription-manager(8)
2
3
4
6 subscription-manager - Registers systems to a subscription management
7 service and then attaches and manages subscriptions for software prod‐
8 ucts.
9
10
12 subscription-manager command [options]
13
14
16 subscription-manager is a client program that registers a system with a
17 subscription management service such as the Customer Portal Subscrip‐
18 tion Management service or on-premise Subscription Asset Manager.
19
20
21 Red Hat provides content updates and support by issuing subscriptions
22 for its products. These subscriptions are applied to systems; once a
23 subscription for a product is attached to a system, that system is al‐
24 lowed to install, update, and receive support for that software prod‐
25 uct. IT administrators need to track these subscriptions and how they
26 are attached. This subscription management is a feature available for
27 Red Hat platforms version 5.7 (and later) and version 6.1 (and later).
28
29
30 For RHEL systems, content is delivered through the Red Hat Customer
31 Portal. Subscriptions and systems are managed globally through the Red
32 Hat subscription management service, which is integrated with the Cus‐
33 tomer Portal. Subscriptions are managed for the local system by using
34 the Red Hat Subscription Manager tool. Subscription Manager is a local
35 client which connects a system with the subscription management ser‐
36 vice.
37
38
39 subscription-manager is the command-line based client for the Red Hat
40 Subscription Manager tool.
41
42
43 Subscription Manager performs several key operations:
44
45 * It registers systems to the Red Hat subscription management
46 service and adds the system to the inventory. Once a system is
47 registered, it can receive updates based on its subscriptions to
48 any kind of software products.
49
50 * It lists both available and used subscriptions.
51
52 * It allows administrators to both attach specific subscriptions
53 to a system and remove those subscriptions.
54
55 Subscription Manager can be used to auto-attach subscriptions to a sys‐
56 tem, as well. The subscription-manager command can even be invoked as
57 part of a kickstart process.
58
59
60 Available subscriptions are based on the specific information about the
61 system's architecture. A subscription is only considered available if
62 the platform and hardware can support that specific product.
63
64
65 Subscription Manager also collects and summarizes system facts related
66 to its hardware, operating system, and other characteristics. These
67 facts can be edited in the Subscription Manager configuration and dis‐
68 played through Subscription Manager.
69
70
71 There is also a Subscription Manager GUI, which can be invoked simply
72 by running subscription-manager-gui from the command line.
73
74
75 Subscription management is only available for RHEL 5.7/6.1 and later
76 systems. Older systems should register to Red Hat Network Classic using
77 the rhn_register command.
78
79
81 subscription-manager has specific options available for each command,
82 depending on what operation is being performed. Subscription Manager
83 commands are related to the different subscription operations:
84
85
86 Note: Please note that using commands that require providing a username
87 using --username , a password using --password , an organization using
88 --org , or environments using --environments must be passed as system
89 arguments in a non-interactive session.
90
91
92 1. register
93
94
95 2. unregister
96
97
98 3. attach
99
100
101 4. auto-attach
102
103
104 5. remove
105
106
107 6. release
108
109
110 7. import
111
112
113 8. redeem
114
115
116 9. list
117
118
119 10. refresh
120
121
122 11. environments
123
124
125 12. repos
126
127
128 13. orgs
129
130
131 14. plugins
132
133
134 15. identity
135
136
137 16. facts
138
139
140 17. clean
141
142
143 18. config
144
145
146 19. version
147
148
149 20. status
150
151
152 21. syspurpose
153
154
155 22. repo-override
156
157
158 Following commands were deprecated: addons, role, service-level, sub‐
159 scribe, unsubscribe, usage, and activate
160
161
162 COMMON OPTIONS
163 -h, --help
164 Prints the specific help information for the given command.
165
166
167 --proxy=PROXY
168 Uses an HTTP proxy. The PROXY name has the format hostname:port.
169
170
171
172 --proxyuser=PROXYUSERNAME
173 Gives the username to use to authenticate to the HTTP proxy.
174
175
176 --proxypass=PROXYPASSWORD
177 Gives the password to use to authenticate to the HTTP proxy.
178
179
180 --noproxy=NOPROXY
181 Specifies a list of domain suffixes which should bypass the HTTP
182 proxy.
183
184
185 --no-progress-messages
186 Disables progress messages that are being displayed when waiting
187 for server response.
188
189
190 REGISTER OPTIONS
191 The register command registers a new system to the subscription manage‐
192 ment service.
193
194 Note: Please note that using commands that require providing a username
195 using --username , a password using --password , an organization using
196 --org , or environments using --environments must be passed as system
197 arguments in a non-interactive session.
198
199
200 --username=USERNAME
201 Gives the username for the account which is registering the sys‐
202 tem; this user account is usually tied to the user account for
203 the content delivery system which supplies the content. Op‐
204 tional, for user-based authentication.
205
206
207 --password=PASSWORD
208 Gives the user account password.
209
210
211 --token=TOKEN
212 Token to use when authorizing against the server.
213
214
215 --serverurl=SERVER_HOSTNAME
216 Passes the name of the subscription service with which to regis‐
217 ter the system. The default value, if this is not given, is the
218 Customer Portal Subscription Management service, subscrip‐
219 tion.rhsm.redhat.com. If there is an on-premise subscription
220 service such as Subscription Asset Manager, this parameter can
221 be used to submit the hostname of the subscription service. For
222 Subscription Asset Manager, if the Subscription Manager tool is
223 configured with the Subscription Asset Manager RPM, then the de‐
224 fault value for the --serverurl parameter is for the on-premise
225 Subscription Asset Manager server.
226
227
228
229 --baseurl=https://CONTENT_SERVICE:PORT/PREFIX
230 Passes the name of the content delivery service to configure the
231 yum service to use to pull down packages. If there is an on-
232 premise subscription service such as Subscription Asset Manager
233 or CloudForms System Engine, this parameter can be used to sub‐
234 mit the URL of the content repository, in the form
235 https://server_name:port/prefix. PREFIX in particular depends
236 on the service type. For example, https://sam.exam‐
237 ple.com:8088/sam is the baseurl for a SAM service.
238 https://sat6.example.com/pulp/repos is the baseurl for a Satel‐
239 lite 6 service with the hostname sat6.example.com .
240 https://cdn.redhat.com is the baseurl for the Red Hat CDN.
241
242
243
244 --name=SYSTEM_NAME
245 Sets the name of the system to register. This defaults to the
246 hostname.
247
248
249
250 --consumerid=CONSUMERID
251 References an existing system inventory ID to resume using a
252 previous registration for this system. The ID is used as an in‐
253 ventory number for the system in the subscription management
254 service database. If the system's identity is lost or corrupted,
255 this option allows it to resume using its previous identity and
256 subscriptions.
257
258
259 --activationkey=KEYS
260 Gives a comma-separated list of product keys to use to redeem or
261 apply specific subscriptions to the system. This is used for
262 preconfigured systems which may already have products installed.
263 Activation keys are issued by an on-premise subscription manage‐
264 ment service, such as Subscription Asset Manager.
265
266 When the --activationkey option is used, it is not necessary to
267 use the --username and --password options, because the authenti‐
268 cation information is implicit in the activation key.
269
270 For example:
271 subscription-manager register --org="IT Dept" --activationkey=1234abcd
272
273
274 --auto-attach
275 Automatically attaches compatible subscriptions to this system.
276
277
278
279 --servicelevel=LEVEL
280 Sets the preferred service level to use with subscriptions added
281 to the system. Service levels are commonly premium, standard,
282 and none, though other levels may be available depending on the
283 product and the contract.
284
285
286 --force
287 When the system is already registered, a new attempt to register
288 will fail with a message reminding the user that the system is
289 already registered. However, passing the --force, option will
290 implicitly attempt to unregister the system first. Beware that
291 the --force option does not guarantee a successful registration.
292 For example, if the registration with --force includes a differ‐
293 ent --serverurl than was used for the original registration, the
294 implicit call to unregister from the original entitlement server
295 will fail with invalid credentials and the registration with
296 force will be aborted. In this case, the user should explicitly
297 unregister from the original entitlement server. If unregister‐
298 ing is not possible, then running subscription-manager clean
299 will effectively abandon the original registration identity and
300 entitlements. Once cleaned, registering a new system identity
301 should succeed with or without force.
302
303
304 --org=ORG
305 Assigns the system to an organization. Infrastructures which are
306 managed on-site may be multi-tenant, meaning that there are mul‐
307 tiple organizations within one customer unit. A system may be
308 assigned manually to one of these organizations. When a system
309 is registered with the Customer Portal, this is not required.
310 When a system is registered with an on-premise application such
311 as Subscription Asset Manager, this argument is required, unless
312 there is only a single organization configured.
313
314
315 --environments=ENV
316 Registers the system to one or more environments within an orga‐
317 nization. This is a comma-separated list and the order is main‐
318 tained.
319
320
321 --release=VERSION
322 Shortcut for "release --set=VERSION"
323
324
325 UNREGISTER OPTIONS
326 The unregister command does two important things. Firstly, it will im‐
327 plicitly remove all of the currently attached subscriptions thereby re‐
328 turning the consumed quantity of entitlements back to their subscrip‐
329 tion pools making them available for other consumers. Secondly, it will
330 remove the system's consumer identity thereby removing its contact with
331 the currently configured subscription management service.
332
333
334 This command has no options.
335
336
337 ATTACH OPTIONS
338 The attach command applies a specific subscription to the system. This
339 command is not possible to use, when the content access mode of the or‐
340 ganization to which the system is registered is simple content access
341 mode.
342
343
344 --auto Automatically attaches the best-matched compatible subscription
345 or subscriptions to the system. This is the default unless
346 --pool or --file are used.
347
348
349 --pool=POOLID
350 Gives the ID for the subscriptions pool (collection of products)
351 to attach to the system. This overrides the default of --auto.
352
353
354 --file=FILE
355 Specifies a file from which to read whitespace-delimited pool
356 IDs. If FILE is "-", the pool IDs will be read from stdin. This
357 overrides the default of --auto.
358
359
360 --quantity=NUMBER
361 Attaches a specified number of subscriptions to the system. Sub‐
362 scriptions may have certain limits on them, like the number of
363 sockets on the system or the number of allowed virtual guests.
364 It is possible to attach multiple subscriptions (or stacking
365 subscriptions) to cover the number of sockets, guests, or other
366 characteristics. May not be used with an auto-attach.
367
368
369
370 --servicelevel=LEVEL
371 Sets the preferred service level to use with subscriptions auto‐
372 matically attached to the system. Service levels are commonly
373 premium, standard, and none, though other levels may be avail‐
374 able depending on the product and the contract. This option can‐
375 not be used when attaching specific pools via --pool or --file.
376
377
378 AUTO-ATTACH OPTIONS
379 The auto-attach command sets whether the ability to check, attach, and
380 update subscriptions occurs automatically on the system. Auto-attaching
381 subscriptions checks the currently-installed products, attached sub‐
382 scriptions, and any changes in available subscriptions every four hours
383 using the rhsmcertd daemon.
384
385
386 --enable
387 Enables the auto-attach option for the system. If there is any
388 change in the subscriptions for the system, any subscriptions
389 expire, or any new products are installed, then subscription-
390 manager detects the changes and automatically attaches the ap‐
391 propriate subscriptions so that the system remains covered.
392
393
394 --disable
395 Disables the auto-attach option for the system. If auto-attach
396 is disabled, then any changes in installed products or subscrip‐
397 tions for the system (including expired subscriptions) must be
398 addressed manually by the administrator.
399
400
401 --show Shows whether auto-attach is enabled on the systems.
402
403
404 REMOVE OPTIONS
405 The remove command removes a subscription from the system. (This does
406 not uninstall the associated products.)
407
408
409 --serial=SERIALNUMBER
410 Gives the serial number of the subscription certificate for the
411 specific product to remove from the system. Subscription cer‐
412 tificates attached to a system are in a certificate, in
413 /etc/pki/entitlement/<serial_number>.pem. To remove multiple
414 subscriptions, use the --serial option multiple times.
415
416
417 --pool=POOLID
418 Removes all subscription certificates for the specified pool id
419 from the system. To remove multiple sets of subscriptions, use
420 the --pool option multiple times.
421
422
423 --all Removes all of the subscriptions attached to a system.
424
425
426
427 RELEASE OPTIONS
428 The release command sets a sticky OS version to use when installing or
429 updating packages. This sets a preference for the minor version of the
430 OS, such as 6.2 or 6.3. This can prevent unplanned or unsupported oper‐
431 ating system version upgrades when an IT environment must maintain a
432 certified configuration.
433
434
435 --list Lists the available OS versions. If a release preference is not
436 set, then there is a message saying it is not set.
437
438
439 --set=RELEASE
440 Sets the minor (Y-stream) release version to use, such as 6.3.
441
442
443 --unset
444 Removes any previously set release version preference.
445
446
447
448 SYSPURPOSE OPTIONS
449 The syspurpose command displays the current configured syspurpose pref‐
450 erences for the system.
451
452
453 The syspurpose command has subcommands for all the various syspurpose
454 preferences and attributes:
455
456
457 1. addons
458
459
460 2. role
461
462
463 3. service-level
464
465
466 4. usage
467
468
469
470 --show Shows the system's current set of syspurpose preference format‐
471 ted as JSON. Single-valued entries for which there is no value
472 will be included in the output with a value of "". List entries
473 which have no value will be included in the output with a value
474 of "[]" (less the quotes).
475
476
477
478 addons options
479 The addons subcommand displays the current configured addons system
480 purpose attribute preference for products installed on the system. For
481 example, if the addons preference is ADDON1, then a subscription with a
482 ADDON1 addon is selected when auto-attaching subscriptions to the sys‐
483 tem.
484
485
486 --show Shows the system's current addons preference. If a addons is not
487 set, then there is a message saying it is not set.
488
489
490 --list Lists the available addons system purpose values.
491
492
493 --username=USERNAME
494 Gives the username for the account to use to connect to the or‐
495 ganization account [Usable with --list on unregistered systems].
496
497
498 --password=PASSWORD
499 Gives the user account password [Usable with --list on unregis‐
500 tered systems].
501
502
503 --token=TOKEN
504 Token to use when authorizing against the server [Usable with
505 --list on unregistered systems].
506
507
508 --org=ORG
509 Identifies the organization for which the addons apply [Usable
510 with --list on unregistered systems].
511
512
513 --add=ADDON
514 Addon to add to the list of requested addons for this system
515
516
517 --remove=ADDON
518 Remove the addon from the list of requested addons.
519
520
521 --unset
522 Removes all addons from the list of requested addons.
523
524
525
526 role options
527 The role subcommand displays the current configured role preference for
528 products installed on the system. For example, if the role preference
529 is "Red Hat Enterprise Linux Server", then a subscription with a "Red
530 Hat Enterprise Linux Server" role is selected when auto-attaching sub‐
531 scriptions to the system.
532
533
534 --show Shows the system's current role preference. If a role is not
535 set, then there is a message saying it is not set.
536
537
538 --list Lists the available role system purpose values.
539
540
541 --username=USERNAME
542 Gives the username for the account to use to connect to the or‐
543 ganization account [Usable with --list on unregistered systems].
544
545
546 --password=PASSWORD
547 Gives the user account password [Usable with --list on unregis‐
548 tered systems].
549
550
551 --token=TOKEN
552 Token to use when authorizing against the server [Usable with
553 --list on unregistered systems].
554
555
556 --org=ORG
557 Identifies the organization for which the role applies [Usable
558 with --list on unregistered systems].
559
560
561 --set=ROLE
562 Role to apply to this system
563
564
565 --unset
566 Removes any previously set role preference.
567
568
569
570 service-level options
571 The service-level subcommand displays the current configured service
572 level preference for products installed on the system. For example, if
573 the service-level preference is standard, then a subscription with a
574 standard service level is selected when auto-attaching subscriptions to
575 the system.
576
577
578 --serverurl=SERVER_URL
579 Server URL in the form of https://hostname:port/prefix [Usable
580 on unregistered systems].
581
582
583 --insecure
584 Do not check the server SSL certificate against available cer‐
585 tificate authorities
586
587
588 --show Shows the system's current service-level preference. If a ser‐
589 vice level is not set, then there is a message saying it is not
590 set.
591
592
593 --list Lists the available service levels.
594
595
596 --username=USERNAME
597 Gives the username for the account to use to connect to the or‐
598 ganization account [Usable with --list on unregistered systems].
599
600
601 --password=PASSWORD
602 Gives the user account password [Usable with --list on unregis‐
603 tered systems].
604
605
606 --token=TOKEN
607 Token to use when authorizing against the server [Usable with
608 --list on unregistered systems].
609
610
611 --set=SERVICE_LEVEL
612 Service level to apply to this system
613
614
615 --unset
616 Removes any previously set service-level preference.
617
618
619
620 usage options
621 The usage subcommand displays the current configured usage preference
622 for products installed on the system. For example, if the usage prefer‐
623 ence is "Production", then a subscription with a "Production" usage is
624 selected when auto-attaching subscriptions to the system.
625
626
627 --show Shows the system's current usage preference. If a usage is not
628 set, then there is a message saying it is not set.
629
630
631 --list Lists the available usage system purpose values.
632
633
634 --username=USERNAME
635 Gives the username for the account to use to connect to the or‐
636 ganization account [Usable with --list on unregistered systems].
637
638
639 --password=PASSWORD
640 Gives the user account password [Usable with --list on unregis‐
641 tered systems].
642
643
644 --token=TOKEN
645 Token to use when authorizing against the server [Usable with
646 --list on unregistered systems].
647
648
649 --org=ORG
650 Identifies the organization for which the usage applies [Usable
651 with --list on unregistered systems].
652
653
654 --set=USAGE
655 Usage to apply to this system
656
657
658 --unset
659 Removes any previously set usage preference.
660
661
662
663 IMPORT OPTIONS
664 The import command imports and applies a subscription certificate for
665 the system which was generated externally, such as in the Customer Por‐
666 tal, and then copied over to the system. Importing can be necessary if
667 a system is preconfigured in the subscription management service or if
668 it is offline or unable to access the subscription management service
669 but it has the proper, relevant subscriptions attached to the system.
670
671
672 --certificate=CERTIFICATE_FILE
673 Points to a certificate PEM file which contains the subscription
674 certificate. This can be used multiple times to import multiple
675 subscription certificates.
676
677
678 REDEEM OPTIONS
679 The redeem command is used for systems that are purchased from third-
680 party vendors that include a subscription. The redemption process es‐
681 sentially auto-attaches the preselected subscription that the vendor
682 supplied to the system.
683
684
685 --email=EMAIL
686 Gives the email account to send the redemption notification mes‐
687 sage to.
688
689
690 --locale=LOCALE
691 Sets the locale to use for the message. If none is given, then
692 it defaults to the local system's locale.
693
694
695
696 LIST OPTIONS
697 The list command lists all of the subscriptions that are compatible
698 with a system. The options allow the list to be filtered by subscrip‐
699 tions that are used by the system or unused subscriptions that are
700 available to the system.
701
702
703 --afterdate=YYYY-MM-DD
704 Shows pools that are active on or after the given date. This is
705 only used with the --available option.
706
707
708 --all Lists all possible subscriptions that have been purchased, even
709 if they don't match the architecture of the system. This is used
710 with the --available option.
711
712
713 --available
714 Lists available subscriptions which are not yet attached to the
715 system.
716
717
718 --consumed
719 Lists all of the subscriptions currently attached to the system.
720
721
722 --installed
723 Lists products which are currently installed on the system which
724 may (or may not) have subscriptions associated with them, as
725 well as products with attached subscriptions which may (or may
726 not) be installed. (default)
727
728
729 --ondate=YYYY-MM-DD
730 Sets the date to use to search for active and available sub‐
731 scriptions. The default (if not explicitly passed) is today's
732 date; using a later date looks for subscriptions which will be
733 active then. This is only used with the --available option.
734
735
736 --no-overlap
737 Shows pools which provide products that are not already covered;
738 only used with --available option.
739
740
741 --match-installed
742 Shows only subscriptions matching products that are currently
743 installed; only used with --available option.
744
745
746 --matches=SEARCH
747 Limits the output of --installed, --available and --consumed to
748 only subscriptions or products which contain SEARCH in the sub‐
749 scription or product information, varying with the list re‐
750 quested and the server version.
751 SEARCH may contain the wildcards ? or * to match a single char‐
752 acter or zero or more characters, respectively. The wildcard
753 characters may be escaped with a backslash to represent a lit‐
754 eral question mark or asterisk. Likewise, to represent a back‐
755 slash, it must be escaped with another backslash.
756
757
758 --pool-only
759 Limits the output of --available and --consumed such that only
760 the pool IDs are displayed. No labels or errors will be printed
761 if this option is specified.
762
763
764 REFRESH OPTIONS
765 The refresh command pulls the latest subscription data from the server.
766 Normally, the system polls the subscription management service at a set
767 interval (4 hours by default) to check for any changes in the available
768 subscriptions. The refresh command checks with the subscription manage‐
769 ment service right then, outside the normal interval. Use of the re‐
770 fresh command will clear caches related to the content access mode of
771 the system and allow the system to retrieve fresh data as necessary.
772
773
774 --force
775 Force regeneration of entitlement certificates on the server be‐
776 fore these certificates are pulled from the server.
777
778
779
780 ENVIRONMENTS OPTIONS
781 The environments command lists all of the environments that have been
782 configured for an organization. This command is only used for organiza‐
783 tions which have a locally-hosted subscription or content service of
784 some kind, like Subscription Asset Manager. The concept of environments
785 -- and therefore this command -- have no meaning for environments which
786 use the Customer Portal Subscription Management services.
787
788
789 --username=USERNAME
790 Gives the username for the account to use to connect to the or‐
791 ganization account.
792
793
794 --password=PASSWORD
795 Gives the user account password.
796
797
798 --token=TOKEN
799 Token to use when authorizing against the server.
800
801
802 --org=ORG
803 Identifies the organization for which to list the configured en‐
804 vironments.
805
806
807 --list Lists all of the environments that have been configured for an
808 organization.
809
810
811 --list-enabled
812 Lists the environments in the order that they have been enabled
813 for this consumer.
814
815
816 --list-disabled
817 Lists all of the environments that have been configured for an
818 organization but not enabled for this consumer.
819
820
821 --set=SET
822 Sets an ordered list of one or more comma-separated environments
823 for this consumer.
824
825
826
827 REPOS OPTIONS
828 The repos command lists all of the repositories that are available to a
829 system. This command is only used for organizations which have a lo‐
830 cally-hosted content service of some kind, like Subscription Asset Man‐
831 ager. With Red Hat's hosted content service, there is only one central
832 repository.
833
834
835 --list Lists all of the repositories that are provided by the content
836 service used by the system.
837
838
839 --list-enabled
840 Lists all of the enabled repositories that are provided by the
841 content service used by the system.
842
843
844 --list-disabled
845 Lists all of the disabled repositories that are provided by the
846 content service used by the system.
847
848
849 --enable=REPO_ID
850 Enables the specified repository, which is made available by the
851 content sources identified in the system subscriptions. To en‐
852 able multiple repositories, use this argument multiple times.
853 Wild cards * and ? are supported. The repositories enabled by
854 this option and disabled by --disable are processed in the same
855 order they are specified.
856
857
858 --disable=REPO_ID
859 Disables the specified repository, which is made available by
860 the content sources identified in the system subscriptions. To
861 disable multiple repositories, use this argument multiple times.
862 Wild cards * and ? are supported. The repositories disabled by
863 this option and enabled by --enable are processed in the same
864 order they are specified.
865
866
867
868 ORGS OPTIONS
869 The orgs command lists all of the organizations which are available to
870 the specified user account. A multi-tenant infrastructure may have mul‐
871 tiple organizations within a single customer, and users may be re‐
872 stricted to access only a subset of the total number of organizations.
873
874
875 --username=USERNAME
876 Gives the username for the account to use to connect to the or‐
877 ganization account.
878
879
880 --password=PASSWORD
881 Gives the user account password.
882
883
884 --token=TOKEN
885 Token to use when authorizing against the server.
886
887
888 --serverurl=SERVER_HOSTNAME
889 Passes the name of the subscription service to use to list all
890 available organizations. The orgs command will list all organi‐
891 zations for the specified service for which the user account is
892 granted access. The default value, if this is not given, is the
893 Customer Portal Subscription Management service, https://sub‐
894 scription.rhsm.redhat.com:443. If there is an on-premise sub‐
895 scription service such as Subscription Asset Manager, this pa‐
896 rameter can be used to submit the hostname of the subscription
897 service, in the form [protocol://]servername[:port][/prefix].
898 For Subscription Asset Manager, if the Subscription Manager tool
899 is configured with the Subscription Asset Manager RPM, then the
900 default value for the --serverurl parameter is for the on-
901 premise Subscription Asset Manager server.
902
903
904
905 PLUGIN OPTIONS
906 The plugins command lists the available subscription-manager plugins.
907
908
909 --list List the available subscription-manager plugins.
910
911
912 --listslots
913 List the available plugin slots
914
915
916 --listhooks
917 List the available plugin slots and the hooks that handle them.
918
919
920 --verbose
921 Show additional info about the plugins, such as the plugin con‐
922 figuration values.
923
924
925 REPO-OVERRIDE OPTIONS
926 The repo-override command allows the user to manage custom content
927 repository settings
928
929
930 --repo The repository to modify (can be specified more than once)
931
932
933 --add=NAME:VALUE
934 Adds a named override with the provided value to repositories
935 specified with the --repo option
936
937
938 --remove=NAME
939 Removes a named override from the repositories specified with
940 the --repo option
941
942
943 --remove-all
944 Removes all overrides from repositories specified with the
945 --repo option
946
947
948 --list Lists all overrides from repositories specified with the --repo
949 option
950
951
952
953 IDENTITY OPTIONS
954 The identity command handles the UUID of a system, which identifies the
955 system to the subscription management service after registration. This
956 command can simply return the UUID or it can be used to restore the
957 registration of a previously-registered system to the subscription man‐
958 agement service.
959
960
961 --regenerate
962 Requests that the subscription management service issue a new
963 identity certificate for the system, using an existing UUID in
964 the original identity certificate. If this is used alone, then
965 the identity command also uses the original identity certificate
966 to bind to the subscription management service, using certifi‐
967 cate-based authentication.
968
969
970 --username=USERNAME
971 Gives the username for the account which is registering the sys‐
972 tem; this user account is usually tied to the user account for
973 the content delivery system which supplies the content. Op‐
974 tional, for user-based authentication.
975
976
977 --password=PASSWORD
978 Gives the user account password. Optional, for user-based au‐
979 thentication.
980
981
982 --token=TOKEN
983 Token to use when authorizing against the server.
984
985
986 --force
987 Regenerates the identity certificate for the system using user‐
988 name/password or token authentication. This is used with the
989 --regenerate option. --regenerate alone will use an existing
990 identity certificate to authenticate to the subscription manage‐
991 ment service. If the certificate is missing or corrupted or in
992 other circumstances, then it may be better to use user authenti‐
993 cation rather than certificate-based authentication. In that
994 case, the --force option requires the username or password or
995 token to be given either as an argument or in response to a
996 prompt.
997
998
999
1000 FACTS OPTIONS
1001 The facts command lists the system information, like the release ver‐
1002 sion, number of CPUs, and other architecture information.
1003
1004
1005 --list Lists the system information. These are simple attribute: value
1006 pairs that reflect much of the information in the /etc/sysconfig
1007 directory
1008 cpu.architecture: x86_64
1009 cpu.core(s)_per_socket: 1
1010 cpu.cpu(s): 2
1011 cpu.cpu_family: 6
1012 cpu.cpu_mhz: 1861.776
1013 cpu.cpu_op-mode(s): 64-bit
1014 cpu.cpu_socket(s): 2
1015 cpu.hypervisor_vendor: KVM
1016 cpu.model: 2
1017 cpu.numa_node(s): 1
1018 cpu.numa_node0_cpu(s): 0,1
1019 cpu.stepping: 3
1020 cpu.thread(s)_per_core: 1
1021 cpu.vendor_id: GenuineIntel
1022 cpu.virtualization_type: full
1023 distribution.id: Santiago
1024 distribution.name: Red Hat Enterprise Linux Workstation
1025 distribution.version: 6.1
1026 ----
1027
1028
1029
1030 --update
1031 Updates the system information. This is particularly important
1032 whenever there is a hardware change (such as adding a CPU) or a
1033 system upgrade because these changes can affect the subscrip‐
1034 tions that are compatible with the system.
1035
1036
1037 CLEAN OPTIONS
1038 The clean command removes all of the subscription and identity data
1039 from the local system without affecting the system information in the
1040 subscription management service. This means that any of the subscrip‐
1041 tions applied to the system are not available for other systems to use.
1042 The clean command is useful in cases where the local subscription in‐
1043 formation is corrupted or lost somehow, and the system will be re-reg‐
1044 istered using the register --consumerid=EXISTING_ID command.
1045
1046
1047 This command has no options.
1048
1049
1050 CONFIG OPTIONS
1051 The config command changes the rhsm.conf configuration file used by
1052 Subscription Manager. Almost all of the connection information used by
1053 Subscription Manager to access the subscription management service,
1054 content server, and any proxies is set in the configuration file, as
1055 well as general configuration parameters like the frequency Subscrip‐
1056 tion Manager checks for subscriptions updates. There are major divi‐
1057 sions in the rhsm.conf file, such as [server] which is used to config‐
1058 ure the subscription management service. When changing the Subscription
1059 Manager configuration, the settings are identified with the format sec‐
1060 tion.name and then the new value. For example:
1061
1062 server.hostname=newsubscription.example.com
1063
1064
1065 --list Prints the current configuration for Subscription Manager.
1066
1067
1068 --remove=section.name
1069 Deletes the current value for the parameter without supplying a
1070 new parameter. A blank value tells Subscription Manager to use
1071 service default values for that parameter. If there are no de‐
1072 faults, then the feature is ignored.
1073
1074
1075 --section.name=VALUE
1076 Sets a parameter to a new, specified value. This is commonly
1077 used for connection settings:
1078
1079 * server.hostname (subscription management service)
1080
1081 * server.proxy
1082
1083 * server.proxy_port
1084
1085 * server.proxy_user
1086
1087 * server.proxy_password
1088
1089 * rhsm.baseurl (content server)
1090
1091 * rhsm.certFrequency
1092
1093
1094 VERSION OPTIONS
1095 The version command displays information about the current Subscription
1096 Manager package, the subscription service the system is registered to
1097 (if it is currently registered), and the subscription management server
1098 that the system is configured to use. For example:
1099
1100 [root@server ~]# subscription-manager version
1101 server type: Red Hat Subscription Management
1102 subscription management server: 0.9.18-1
1103 subscription management rules: 5.9
1104 subscription-manager: 1.12.1-1.git.28.5cd97a5.fc20
1105 python-rhsm: 1.11.4-1.git.1.2f38ded.fc20
1106
1107
1108 This command has no options.
1109
1110
1111
1112 STATUS OPTIONS
1113 The status command shows the current status of the products and at‐
1114 tached subscriptions for the system. If some products are not fully
1115 covered or subscriptions have expired, then the status command shows
1116 why subscriptions are not current and returns an error code.
1117
1118 [root@server ~]# subscription-manager status
1119 +-------------------------------------------+
1120 System Status Details
1121 +-------------------------------------------+
1122 Overall Status: Current
1123
1124
1125
1126 --ondate=DATE
1127 Shows the system status for a specific date in the future. The
1128 format of the date is YYYY-MM-DD.
1129
1130 [root@server ~]# subscription-manager status --ondate=2014-01-01
1131 +-------------------------------------------+
1132 System Status Details
1133 +-------------------------------------------+
1134 Overall Status: Insufficient
1135
1136
1137 DEPRECATED COMMANDS
1138 As the structures of subscription configuration have changed, some of
1139 the original management commands have become obsolete. These commands
1140 have been replaced with updated commands.
1141
1142
1143 subscribe
1144 This has been replaced with attach. A similar registration op‐
1145 tion, --subscribe, has also be replaced with --auto-attach.
1146
1147
1148 unsubscribe
1149 This has been replaced with remove.
1150
1151
1152 activate
1153 This has been replaced with redeem.
1154
1155
1156 addons This has been replaced with syspurpose addons.
1157
1158
1159 role This has been replaced with syspurpose role.
1160
1161
1162 service-level
1163 This has been replaced with syspurpose service-level.
1164
1165
1166 usage This has been replaced with syspurpose usage.
1167
1168
1170 subscription-manager has two major tasks:
1171
1172
1173 1. Handling the registration for a given system to a subscrip‐
1174 tion management service
1175
1176
1177 2. Handling the product subscriptions for installed products on
1178 a system
1179
1180
1181 subscription-manager makes it easier for network administrators to
1182 maintain parity between software subscriptions and updates and their
1183 installed products by tracking and managing what subscriptions are at‐
1184 tached to a system and when those subscriptions expire or are exceeded.
1185
1186
1187
1188 REGISTERING AND UNREGISTERING MACHINES
1189 A system is either registered to a subscription management service --
1190 which makes all of the subscriptions available to the system -- or it
1191 is not registered. Unregistered systems necessarily lack valid software
1192 subscriptions because there is no way to record that the subscriptions
1193 have been used nor any way to renew them.
1194
1195
1196 The default subscription management service in the Subscription Manager
1197 configuration is the Customer Portal Subscription Management service.
1198 The configuration file can be edited before the system is registered to
1199 point to an on-premise subscription management service like Subscrip‐
1200 tion Asset Manager.
1201
1202
1203 Systems are usually registered to a subscription management service as
1204 part of their initial configuration, such as the kickstart process.
1205 However, systems can be registered manually after they are configured,
1206 can be removed from a content service, or re-registered.
1207
1208
1209 If a system has never been registered (not even during first boot),
1210 then the register command will register the system with whatever sub‐
1211 scription management service is configured in the /etc/rhsm/rhsm.conf
1212 file. This command requires, at a minimum, the username and password or
1213 token for an account to connect to the subscription management service.
1214 If the credentials aren't passed with the command, then subscription-
1215 manager prompts for the username and password interactively.
1216
1217
1218 When there is a single organization or when using the Customer Portal
1219 Subscription Management service, all that is required is the user‐
1220 name/password set or the token is used. For example:
1221
1222 subscription-manager register --username=admin --password=secret or subscription-manager register --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo
1223
1224
1225 With on-premise subscription services, such as Subscription Asset Man‐
1226 ager, the infrastructure is more complex. The local administrator can
1227 define independent groups called organizations which represent physical
1228 or organizational divisions (--org). Those organizations can be subdi‐
1229 vided into environments (--environment). Optionally, the information
1230 about what subscription service (--serverurl) and content delivery net‐
1231 work (--baseurl) to use for the system registration can also be passed
1232 (which overrides the Red Hat Subscription Manager settings). The server
1233 and content URLs are usually configured in the Subscription Manager
1234 configuration before registering a system.
1235
1236 subscription-manager register --username=admin --password=secret
1237 --org="IT Dept" --environment="local dev" --serverurl=local-cloudforms.example.com --baseurl=https://local-cloudforms.example.com:8088/cfFe
1238
1239
1240
1241 If a system is in a multi-tenant environment and the organization is
1242 not provided with the registration request, registration fails with a
1243 remote server error. In the rhsm.log, there will be errors about being
1244 unable to load the owners interface.
1245
1246
1247
1248 If a system is registered and then somehow its subscription information
1249 is lost -- a drive crashes or the certificates are deleted or corrupted
1250 -- the system can be re-registered, with all of its subscriptions re‐
1251 stored, by registering with the existing ID.
1252
1253 subscription-manager register --username=admin
1254 --password=secret --consumerid=1234abcd
1255
1256
1257 A system uses an SSL client certificate (its identity certificate) to
1258 authenticate to the subscriptions system to check for updates or
1259 changes to subscriptions. If the identity certificate is lost or cor‐
1260 rupted, it can be regenerated using the identity command.
1261
1262 subscription-manager identity --regenerate
1263
1264
1265 Using the --force option will prompt for the username and password for
1266 the account, if one isn't given, and then return the new inventory ID
1267 and the hostname of the registered system.
1268
1269 subscription-manager identity --force
1270 Username: jsmith
1271 Password:
1272 eff9a4c9-3579-49e5-a52f-83f2db29ab52 server.example.com
1273
1274
1275
1276 A system is unregistered and removed from the subscription management
1277 service simply by running the unregister command. Unregistering a sys‐
1278 tem and removing its attached subscriptions can free up subscriptions
1279 when a system is taken offline or moved to a different department.
1280
1281 subscription-manager unregister
1282
1283
1284 An option with registration, --auto-attach, will automatically attach
1285 the subscriptions pool which best matches the system architecture and
1286 configuration to the newly-registered system. This option attaches sub‐
1287 scriptions as part of the registration process, rather than separately
1288 managing subscriptions.
1289
1290 subscription-manager register --username=admin --password=secret
1291 --auto-attach
1292
1293
1294 Auto-attach also supports an option to set a preferred service level
1295 with the selected subscriptions, the --servicelevel option. In this
1296 case, the --servicelevel option sets a preference that helps the auto-
1297 attach process select appropriate subscriptions. For example, if the
1298 preferred service level for a production server is premium, and there
1299 are three matching subscriptions with different service levels (none,
1300 standard, and premium), the auto-attach process selects the subscrip‐
1301 tion which offers a premium service level.
1302
1303 subscription-manager register --username=admin --password=secret
1304 --auto-attach --servicelevel=premium
1305
1306
1307 LISTING, ATTACHING, AND REMOVING SUBSCRIPTIONS FOR PRODUCTS
1308 A subscription is essentially the right to install, use, and receive
1309 updates for a Red Hat product. (Sometimes multiple individual software
1310 products are bundled together into a single subscription.) When a sys‐
1311 tem is registered, the subscription management service is aware of the
1312 system and has a list of all of the possible product subscriptions that
1313 the system can install and use. A subscription is applied to a system
1314 when the system is attached to the subscription pool that makes that
1315 product available. A system releases or removes that subscription
1316 (meaning, it removes that subscription so that another system can use
1317 that subscription count).
1318
1319
1320 list command shows you what subscriptions are available specifically to
1321 the system (meaning subscriptions which are active, have available
1322 quantities, and match the hardware and architecture) or all subscrip‐
1323 tions for the organization. Using the --ondate option shows subscrip‐
1324 tions that are or will be active at a specific time (otherwise, it
1325 shows subscriptions which are active today).
1326
1327 subscription-manager list --available --ondate=2012-01-31
1328 +-------------------------------------------+
1329 Available Subscriptions
1330 +-------------------------------------------+
1331 Subscription Name: Red Hat Enterprise Linux
1332 SKU: SYS0395
1333 Pool Id: 8a85f981302cbaf201302d899adf05a9
1334 Quantity: 249237
1335 Service Level: None
1336 Service Type: None
1337 Multi-Entitlement: No
1338 Starts: 01/01/2021
1339 Ends: 01/01/2022
1340 Machine Type: physical
1341
1342
1343 The list command can also be used to show what products you currently
1344 have installed, as a way of tracking what products you have versus what
1345 subscriptions you have on the system.
1346
1347 subscription-manager list --installed
1348
1349 +-------------------------------------------+
1350 Installed Product Status
1351 +-------------------------------------------+
1352
1353 ProductName: Red Hat Enterprise Linux Server
1354 Product ID: 69
1355 Version: 6.3
1356 Arch: x86_64
1357 Status: Subscribed
1358 Started: 07/26/2012
1359 Ends: 08/31/2015
1360
1361
1362 The list can be filtered to only include products or subscriptions that
1363 match the query string provided to --matches option.
1364
1365 subscription-manager list --installed --matches="*Server*"
1366
1367 +-------------------------------------------+
1368 Installed Product Status
1369 +-------------------------------------------+
1370
1371 ProductName: Red Hat Enterprise Linux Server
1372 Product ID: 69
1373 Version: 6.3
1374 Arch: x86_64
1375 Status: Subscribed
1376 Started: 07/26/2012
1377 Ends: 08/31/2015
1378
1379
1380 Attaching a subscription requires the ID for the subscription pool (the
1381 --pool option). For example:
1382
1383 subscription-manager attach
1384 --pool=ff8080812bc382e3012bc3845da100d2
1385
1386 As with the register command, the system can be auto-attached to the
1387 best-fitting subscriptions. This is the default action and is equiva‐
1388 lent to using the --auto option:
1389
1390 subscription-manager attach
1391
1392
1393
1394 Auto-attach also supports an option to set a preferred service level
1395 with the selected subscriptions, the --servicelevel option. In this
1396 case, the --servicelevel option sets a preference that helps the auto-
1397 attach process select appropriate subscriptions. For example, if the
1398 preferred service level for a production server is premium, and there
1399 are three matching subscriptions with different service levels (none,
1400 standard, and premium), the auto-attach process selects the subscrip‐
1401 tion which offers a premium subscription.
1402
1403 subscription-manager attach --servicelevel=premium
1404
1405
1406 Some subscriptions define a count based on attributes of the system it‐
1407 self, like the number of sockets or the number of virtual guests on a
1408 host. You can combine multiple subscriptions together to cover the
1409 count. For example, if there is a four socket server, you can use two
1410 subscriptions for "RHEL Server for Two Sockets" to cover the socket
1411 count. To specify the number of subscriptions to use, use the --quan‐
1412 tity option. For example:
1413
1414 subscription-manager attach
1415 --pool=ff8080812bc382e3012bc3845da100d2
1416 --quantity=2
1417
1418
1419 Removing subscription from a system releases the subscription back into
1420 the pool. The system remains registered with the subscription manage‐
1421 ment service. Each product has an identifying X.509 certificate in‐
1422 stalled with it. To remove a subscription for a specific product, spec‐
1423 ify the serial number (or numbers, in multiple --serial options) of the
1424 certificate:
1425
1426 subscription-manager remove --serial=1128750306742160
1427
1428
1429 Giving the remove command with the --all option removes every subscrip‐
1430 tion the system has used.
1431
1432
1433
1434 REDEEMING EXISTING SUBSCRIPTIONS
1435 Sometimes, a system may come preconfigured with products and subscrip‐
1436 tions. Rather than attaching a pool and claiming a subscription, this
1437 system simply needs to redeem its existing subscriptions.
1438
1439
1440 After registration, subscriptions on preconfigured systems can be
1441 claimed using the redeem command, which essentially auto-attaches the
1442 system to its preexisting subscriptions.
1443
1444 subscription-manager redeem --email=admin@example.com --org="IT Dept"
1445
1446
1447 VIEWING LOCAL SUBSCRIPTION & CONTENT PROVIDER INFORMATION
1448 Red Hat has a hosted environment, through the Customer Portal, that
1449 provides centralized access to subscription management and content
1450 repositories. However, organizations can use other tools -- like Sub‐
1451 scription Manager -- for content hosting and subscription management.
1452 With a local content provider, the organization, environments, reposi‐
1453 tories, and other structural configuration is performed in the content
1454 provider. Red Hat Subscription Manager can be used to display this in‐
1455 formation, using the environments, orgs, and repos commands.
1456
1457 subscription-manager repos --list
1458
1459 subscription-manager environments --username=jsmith
1460 --password=secret --org=prod
1461
1462 or
1463
1464 subscription-manager environments --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo --org=prod
1465
1466
1467 subscription-manager orgs --username=jsmith
1468 --password=secret
1469
1470 or
1471
1472 subscription-manager orgs --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo
1473
1474
1475 CHANGING SUBSCRIPTION MANAGER CONFIGURATION
1476 The Subscription Manager CLI and GUI both use the /etc/rhsm/rhsm.conf
1477 file for configuration, including what content and subscription manage‐
1478 ment services to use and management settings like auto-attaching. This
1479 configuration file can be edited directly, or it can be edited using
1480 the config command. Parameters and values are passed as arguments with
1481 the config command in the format --section.parameter=value , where sec‐
1482 tion is the configuration section in the file: server, rhsm, rhsmcertd
1483 or logging.
1484
1485
1486 For example, to change the hostname of the subscription management ser‐
1487 vice host:
1488
1489 subscription-manager config --server.hostname=myserver.example.com
1490
1491
1492 The entries in the logging section are somewhat special. The keys in
1493 this section are a name of a logger. The values are the logging level.
1494
1495 Valid levels are one of: DEBUG , INFO , WARNING , ERROR , or CRITICAL
1496
1497 Valid logger names are the full module path of any Subscription Manager
1498 module. For example: subscription_manager or subscription_manager.man‐
1499 agercli
1500
1501
1502 There are three main top-level loggers: subscription_manager, rhsm, and
1503 rhsm-app. All logger names begin with one of the above.
1504
1505
1506 To set the default log level for all loggers (that are not otherwise
1507 set in the logging section), edit the default_log_level key in
1508 /etc/rhsm/rhsm.conf
1509
1510
1511
1512 UPDATING FACTS
1513 The information about a system, such as its hardware and CPU, its oper‐
1514 ating system versions, and memory, are collected by Subscription Man‐
1515 ager in a list of facts. Subscription Manager uses these facts to de‐
1516 termine what purchased subscriptions are compatible with the system.
1517 Whenever these facts change (such as installing an additional CPU), the
1518 facts can be updated immediately using the facts command.
1519
1520 subscription-manager facts --update
1521
1522 The collected facts can also be overridden by creating a JSON file in
1523 the /etc/rhsm/facts/ directory. These have simple formats that define a
1524 fact and value:
1525
1526 {"fact1": "value1","fact2": "value2"}
1527
1528
1529 Any fact override file must have a .facts extension.
1530
1531
1532 When these fact files are added, running the facts command will update
1533 the collected facts with the new, manual facts or values.
1534
1535
1536 SUBSCRIPTIONS AND KICKSTART
1537 The subscription-manager tool can be run as a post-install script as
1538 part of the kickstart installation process. This allows subscription
1539 management (registering and applying subscriptions) to be automated
1540 along with installation. For example:
1541
1542 %post --log=/root/ks-post.log
1543 /usr/sbin/subscription-manager register --username admin --password secret --org 'east colo' --auto-attach --servicelevel=premium --force
1544
1545
1547 The subscription-manager tool uses outgoing HTTPS requests. In the de‐
1548 fault configuration it will use HTTPS on port 443 to the subscription
1549 servers subscription.rhsm.redhat.com and to the content delivery ser‐
1550 vice cdn.redhat.com.
1551
1552 For information about the network addresses that subscription-manager
1553 and the subscription-manager yum plugin use see https://access.red‐
1554 hat.com/site/solutions/59586
1555
1556
1558 subscription-manager can be configured to use a proxy in several ways:
1559
1560 * via standard HTTP_PROXY , HTTPS_PROXY , NO_PROXY environment
1561 variables (environment-level settings)
1562
1563 * via options in /etc/rhsm/rhsm.conf (application-level set‐
1564 tings)
1565
1566 * via command-line arguments (command-level overrides)
1567
1568
1569 Although subscription-manager respects environment variables for proxy
1570 configuration, this should be avoided in favor of the configuration
1571 file, because the daemons (ex. rhsmcertd ) do not provide ways to mod‐
1572 ify their environments.
1573
1574 Each option of the proxy configuration (hostname, port, host/domain
1575 pattern blocklist, username, password) is read independently, with
1576 precedence being command-line over configuration over environment, and
1577 then the resulting set of options is used to configure the proxy con‐
1578 figuration.
1579
1580 For example, if the HTTP_PROXY environment variable is set and no_proxy
1581 is set in /etc/rhsm/rhsm.conf then both are present in the effective
1582 proxy configuration.
1583
1584 If two equivalent options are set in different places, then the prece‐
1585 dence determines which value is effective.
1586
1587 For example, the NO_PROXY environment variable is set and the no_proxy
1588 configuration file option is set, then the value from the configuration
1589 file is the effective value.
1590
1591
1593 Default log location of the subscription-manager is
1594 /var/log/rhsm/rhsm.log. When the program is run under non-root user
1595 (e.g. as dnf plugin) the logs are written to
1596 $XDG_CACHE_HOME/rhsm/rhsm.log.
1597
1598 If the directory isn't writable, the logs are printed to stderr.
1599
1600
1602 * /etc/pki/consumer/*.pem
1603
1604 * /etc/pki/entitlement/<serial>.pem
1605
1606 * /etc/pki/product/*.pem
1607
1608 * /etc/rhsm/rhsm.conf
1609
1610 * /etc/rhsm/facts/*.facts
1611
1612 * /var/log/rhsm/rhsm.log
1613
1614
1616 Deon Lackey, <dlackey@redhat.com>, and Pradeep Kilambi, <pkilambi@red‐
1617 hat.com>
1618
1619
1620
1621
1622 subscription-manager(8)