1subscription-manager(8) Subscription Management subscription-manager(8)
2
6 subscription-manager - Registers systems to a subscription management
7 service and then attaches and manages subscriptions for software prod‐
8 ucts.
9
12 subscription-manager command [options]
13
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 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 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 subscription-manager is the command-line based client for the Red Hat
40 Subscription Manager tool.
41 Subscription Manager performs several key operations:
44 * 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 * It lists both available and used subscriptions.
51 * It allows administrators to both attach specific subscriptions
53 to a system and remove those subscriptions.
54 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 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 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 There is also a Subscription Manager GUI, which can be invoked simply
72 by running subscription-manager-gui from the command line.
73 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
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 1. register
87 2. unregister
90 3. attach
93 4. auto-attach
96 5. remove
99 6. release
102 7. import
105 8. redeem
108 9. list
111 10. refresh
114 11. environments
117 12. repos
120 13. orgs
123 14. plugins
126 15. identity
129 16. facts
132 17. clean
135 18. config
138 19. version
141 20. status
144 21. syspurpose
147 22. repo-override
150 Following commands were deprecated: addons, role, service-level, sub‐
153 scribe, unsubscribe, usage, and activate
154 COMMON OPTIONS
157 -h, --help
158 Prints the specific help information for the given command.
159 --proxy=PROXY
162 Uses an HTTP proxy. The PROXY name has the format hostname:port.
163 --proxyuser=PROXYUSERNAME
167 Gives the username to use to authenticate to the HTTP proxy.
168 --proxypass=PROXYPASSWORD
171 Gives the password to use to authenticate to the HTTP proxy.
172 --noproxy=NOPROXY
175 Specifies a list of domain suffixes which should bypass the HTTP
176 proxy.
177 REGISTER OPTIONS
180 The register command registers a new system to the subscription manage‐
181 ment service.
182 --username=USERNAME
185 Gives the username for the account which is registering the sys‐
186 tem; this user account is usually tied to the user account for
187 the content delivery system which supplies the content. Op‐
188 tional, for user-based authentication.
189 --password=PASSWORD
192 Gives the user account password.
193 --token=TOKEN
196 Token to use when authorizing against the server.
197 --serverurl=SERVER_HOSTNAME
200 Passes the name of the subscription service with which to regis‐
201 ter the system. The default value, if this is not given, is the
202 Customer Portal Subscription Management service, subscrip‐
203 tion.rhsm.redhat.com. If there is an on-premise subscription
204 service such as Subscription Asset Manager, this parameter can
205 be used to submit the hostname of the subscription service. For
206 Subscription Asset Manager, if the Subscription Manager tool is
207 configured with the Subscription Asset Manager RPM, then the de‐
208 fault value for the --serverurl parameter is for the on-premise
209 Subscription Asset Manager server.
210 --baseurl=https://CONTENT_SERVICE:PORT/PREFIX
214 Passes the name of the content delivery service to configure the
215 yum service to use to pull down packages. If there is an on-
216 premise subscription service such as Subscription Asset Manager
217 or CloudForms System Engine, this parameter can be used to sub‐
218 mit the URL of the content repository, in the form
219 https://server_name:port/prefix. PREFIX in particular depends
220 on the service type. For example, https://sam.exam‐
221 ple.com:8088/sam is the baseurl for a SAM service.
222 https://sat6.example.com/pulp/repos is the baseurl for a Satel‐
223 lite 6 service with the hostname sat6.example.com .
224 https://cdn.redhat.com is the baseurl for the Red Hat CDN.
225 --name=SYSTEM_NAME
229 Sets the name of the system to register. This defaults to the
230 hostname.
231 --consumerid=CONSUMERID
235 References an existing system inventory ID to resume using a
236 previous registration for this system. The ID is used as an in‐
237 ventory number for the system in the subscription management
238 service database. If the system's identity is lost or corrupted,
239 this option allows it to resume using its previous identity and
240 subscriptions.
241 --activationkey=KEYS
244 Gives a comma-separated list of product keys to use to redeem or
245 apply specific subscriptions to the system. This is used for
246 preconfigured systems which may already have products installed.
247 Activation keys are issued by an on-premise subscription manage‐
248 ment service, such as Subscription Asset Manager.
249 When the --activationkey option is used, it is not necessary to
251 use the --username and --password options, because the authenti‐
252 cation information is implicit in the activation key.
253 For example:
255 subscription-manager register --org="IT Dept" --activationkey=1234abcd
256 --auto-attach
259 Automatically attaches compatible subscriptions to this system.
260 --servicelevel=LEVEL
264 Sets the preferred service level to use with subscriptions added
265 to the system. Service levels are commonly premium, standard,
266 and none, though other levels may be available depending on the
267 product and the contract.
268 --force
271 When the system is already registered, a new attempt to register
272 will fail with a message reminding the user that the system is
273 already registered. However, passing the --force, option will
274 implicitly attempt to unregister the system first. Beware that
275 the --force option does not guarantee a successful registration.
276 For example, if the registration with --force includes a differ‐
277 ent --serverurl than was used for the original registration, the
278 implicit call to unregister from the original entitlement server
279 will fail with invalid credentials and the registration with
280 force will be aborted. In this case, the user should explicitly
281 unregister from the original entitlement server. If unregister‐
282 ing is not possible, then running subscription-manager clean
283 will effectively abandon the original registration identity and
284 entitlements. Once cleaned, registering a new system identity
285 should succeed with or without force.
286 --org=ORG
289 Assigns the system to an organization. Infrastructures which are
290 managed on-site may be multi-tenant, meaning that there are mul‐
291 tiple organizations within one customer unit. A system may be
292 assigned manually to one of these organizations. When a system
293 is registered with the Customer Portal, this is not required.
294 When a system is registered with an on-premise application such
295 as Subscription Asset Manager, this argument is required, unless
296 there is only a single organization configured.
297 --environment=ENV
300 Registers the system to an environment within an organization.
301 --release=VERSION
304 Shortcut for "release --set=VERSION"
305 UNREGISTER OPTIONS
308 The unregister command does two important things. Firstly, it will im‐
309 plicitly remove all of the currently attached subscriptions thereby re‐
310 turning the consumed quantity of entitlements back to their subscrip‐
311 tion pools making them available for other consumers. Secondly, it will
312 remove the system's consumer identity thereby removing its contact with
313 the currently configured subscription management service.
314 This command has no options.
317 ATTACH OPTIONS
320 The attach command applies a specific subscription to the system.
321 --auto Automatically attaches the best-matched compatible subscription
324 or subscriptions to the system. This is the default unless
325 --pool or --file are used.
326 --pool=POOLID
329 Gives the ID for the subscriptions pool (collection of products)
330 to attach to the system. This overrides the default of --auto.
331 --file=FILE
334 Specifies a file from which to read whitespace-delimited pool
335 IDs. If FILE is "-", the pool IDs will be read from stdin. This
336 overrides the default of --auto.
337 --quantity=NUMBER
340 Attaches a specified number of subscriptions to the system. Sub‐
341 scriptions may have certain limits on them, like the number of
342 sockets on the system or the number of allowed virtual guests.
343 It is possible to attach multiple subscriptions (or stacking
344 subscriptions) to cover the number of sockets, guests, or other
345 characteristics. May not be used with an auto-attach.
346 --servicelevel=LEVEL
350 Sets the preferred service level to use with subscriptions auto‐
351 matically attached to the system. Service levels are commonly
352 premium, standard, and none, though other levels may be avail‐
353 able depending on the product and the contract. This option can‐
354 not be used when attaching specific pools via --pool or --file.
355 AUTO-ATTACH OPTIONS
358 The auto-attach command sets whether the ability to check, attach, and
359 update subscriptions occurs automatically on the system. Auto-attaching
360 subscriptions checks the currently-installed products, attached sub‐
361 scriptions, and any changes in available subscriptions every four hours
362 using the rhsmcertd daemon.
363 --enable
366 Enables the auto-attach option for the system. If there is any
367 change in the subscriptions for the system, any subscriptions
368 expire, or any new products are installed, then subscription-
369 manager detects the changes and automatically attaches the ap‐
370 propriate subscriptions so that the system remains covered.
371 --disable
374 Disables the auto-attach option for the system. If auto-attach
375 is disabled, then any changes in installed products or subscrip‐
376 tions for the system (including expired subscriptions) must be
377 addressed manually by the administrator.
378 --show Shows whether auto-attach is enabled on the systems.
381 REMOVE OPTIONS
384 The remove command removes a subscription from the system. (This does
385 not uninstall the associated products.)
386 --serial=SERIALNUMBER
389 Gives the serial number of the subscription certificate for the
390 specific product to remove from the system. Subscription cer‐
391 tificates attached to a system are in a certificate, in
392 /etc/pki/entitlement/<serial_number>.pem. To remove multiple
393 subscriptions, use the --serial option multiple times.
394 --pool=POOLID
397 Removes all subscription certificates for the specified pool id
398 from the system. To remove multiple sets of subscriptions, use
399 the --pool option multiple times.
400 --all Removes all of the subscriptions attached to a system.
403 RELEASE OPTIONS
407 The release command sets a sticky OS version to use when installing or
408 updating packages. This sets a preference for the minor version of the
409 OS, such as 6.2 or 6.3. This can prevent unplanned or unsupported oper‐
410 ating system version upgrades when an IT environment must maintain a
411 certified configuration.
412 --list Lists the available OS versions. If a release preference is not
415 set, then there is a message saying it is not set.
416 --set=RELEASE
419 Sets the minor (Y-stream) release version to use, such as 6.3.
420 --unset
423 Removes any previously set release version preference.
424 SYSPURPOSE OPTIONS
428 The syspurpose command displays the current configured syspurpose pref‐
429 erences for the system.
430 The syspurpose command has subcommands for all the various syspurpose
433 preferences and attributes:
434 1. addons
437 2. role
440 3. service-level
443 4. usage
446 --show Shows the system's current set of syspurpose preference format‐
450 ted as JSON. Single-valued entries for which there is no value
451 will be included in the output with a value of "". List entries
452 which have no value will be included in the output with a value
453 of "[]" (less the quotes).
454 addons options
458 The addons subcommand displays the current configured addons system
459 purpose attribute preference for products installed on the system. For
460 example, if the addons preference is ADDON1, then a subscription with a
461 ADDON1 addon is selected when auto-attaching subscriptions to the sys‐
462 tem.
463 --show Shows the system's current addons preference. If a addons is not
466 set, then there is a message saying it is not set.
467 --list Lists the available addons system purpose values.
470 --username=USERNAME
473 Gives the username for the account to use to connect to the or‐
474 ganization account [Usable with --list on unregistered systems].
475 --password=PASSWORD
478 Gives the user account password [Usable with --list on unregis‐
479 tered systems].
480 --token=TOKEN
483 Token to use when authorizing against the server [Usable with
484 --list on unregistered systems].
485 --org=ORG
488 Identifies the organization for which the addons apply [Usable
489 with --list on unregistered systems].
490 --add=ADDON
493 Addon to add to the list of requested addons for this system
494 --remove=ADDON
497 Remove the addon from the list of requested addons.
498 --unset
501 Removes all addons from the list of requested addons.
502 role options
506 The role subcommand displays the current configured role preference for
507 products installed on the system. For example, if the role preference
508 is "Red Hat Enterprise Linux Server", then a subscription with a "Red
509 Hat Enterprise Linux Server" role is selected when auto-attaching sub‐
510 scriptions to the system.
511 --show Shows the system's current role preference. If a role is not
514 set, then there is a message saying it is not set.
515 --list Lists the available role system purpose values.
518 --username=USERNAME
521 Gives the username for the account to use to connect to the or‐
522 ganization account [Usable with --list on unregistered systems].
523 --password=PASSWORD
526 Gives the user account password [Usable with --list on unregis‐
527 tered systems].
528 --token=TOKEN
531 Token to use when authorizing against the server [Usable with
532 --list on unregistered systems].
533 --org=ORG
536 Identifies the organization for which the role applies [Usable
537 with --list on unregistered systems].
538 --set=ROLE
541 Role to apply to this system
542 --unset
545 Removes any previously set role preference.
546 service-level options
550 The service-level subcommand displays the current configured service
551 level preference for products installed on the system. For example, if
552 the service-level preference is standard, then a subscription with a
553 standard service level is selected when auto-attaching subscriptions to
554 the system.
555 --serverurl=SERVER_URL
558 Server URL in the form of https://hostname:port/prefix
559 --insecure
562 Do not check the server SSL certificate against available cer‐
563 tificate authorities
564 --show Shows the system's current service-level preference. If a ser‐
567 vice level is not set, then there is a message saying it is not
568 set.
569 --list Lists the available service levels.
572 --username=USERNAME
575 Gives the username for the account to use to connect to the or‐
576 ganization account [Usable with --list on unregistered systems].
577 --password=PASSWORD
580 Gives the user account password [Usable with --list on unregis‐
581 tered systems].
582 --token=TOKEN
585 Token to use when authorizing against the server [Usable with
586 --list on unregistered systems].
587 --set=SERVICE_LEVEL
590 Service level to apply to this system
591 --unset
594 Removes any previously set service-level preference.
595 usage options
599 The usage subcommand displays the current configured usage preference
600 for products installed on the system. For example, if the usage prefer‐
601 ence is "Production", then a subscription with a "Production" usage is
602 selected when auto-attaching subscriptions to the system.
603 --show Shows the system's current usage preference. If a usage is not
606 set, then there is a message saying it is not set.
607 --list Lists the available usage system purpose values.
610 --username=USERNAME
613 Gives the username for the account to use to connect to the or‐
614 ganization account [Usable with --list on unregistered systems].
615 --password=PASSWORD
618 Gives the user account password [Usable with --list on unregis‐
619 tered systems].
620 --token=TOKEN
623 Token to use when authorizing against the server [Usable with
624 --list on unregistered systems].
625 --org=ORG
628 Identifies the organization for which the usage applies [Usable
629 with --list on unregistered systems].
630 --set=USAGE
633 Usage to apply to this system
634 --unset
637 Removes any previously set usage preference.
638 IMPORT OPTIONS
642 The import command imports and applies a subscription certificate for
643 the system which was generated externally, such as in the Customer Por‐
644 tal, and then copied over to the system. Importing can be necessary if
645 a system is preconfigured in the subscription management service or if
646 it is offline or unable to access the subscription management service
647 but it has the proper, relevant subscriptions attached to the system.
648 --certificate=CERTIFICATE_FILE
651 Points to a certificate PEM file which contains the subscription
652 certificate. This can be used multiple times to import multiple
653 subscription certificates.
654 REDEEM OPTIONS
657 The redeem command is used for systems that are purchased from third-
658 party vendors that include a subscription. The redemption process es‐
659 sentially auto-attaches the preselected subscription that the vendor
660 supplied to the system.
661 --email=EMAIL
664 Gives the email account to send the redemption notification mes‐
665 sage to.
666 --locale=LOCALE
669 Sets the locale to use for the message. If none is given, then
670 it defaults to the local system's locale.
671 LIST OPTIONS
675 The list command lists all of the subscriptions that are compatible
676 with a system. The options allow the list to be filtered by subscrip‐
677 tions that are used by the system or unused subscriptions that are
678 available to the system.
679 --afterdate=YYYY-MM-DD
682 Shows pools that are active on or after the given date. This is
683 only used with the --available option.
684 --all Lists all possible subscriptions that have been purchased, even
687 if they don't match the architecture of the system. This is used
688 with the --available option.
689 --available
692 Lists available subscriptions which are not yet attached to the
693 system.
694 --consumed
697 Lists all of the subscriptions currently attached to the system.
698 --installed
701 Lists products which are currently installed on the system which
702 may (or may not) have subscriptions associated with them, as
703 well as products with attached subscriptions which may (or may
704 not) be installed. (default)
705 --ondate=YYYY-MM-DD
708 Sets the date to use to search for active and available sub‐
709 scriptions. The default (if not explicitly passed) is today's
710 date; using a later date looks for subscriptions which will be
711 active then. This is only used with the --available option.
712 --no-overlap
715 Shows pools which provide products that are not already covered;
716 only used with --available option.
717 --match-installed
720 Shows only subscriptions matching products that are currently
721 installed; only used with --available option.
722 --matches=SEARCH
725 Limits the output of --installed, --available and --consumed to
726 only subscriptions or products which contain SEARCH in the sub‐
727 scription or product information, varying with the list re‐
728 quested and the server version.
729 SEARCH may contain the wildcards ? or * to match a single char‐
730 acter or zero or more characters, respectively. The wildcard
731 characters may be escaped with a backslash to represent a lit‐
732 eral question mark or asterisk. Likewise, to represent a back‐
733 slash, it must be escaped with another backslash.
734 --pool-only
737 Limits the output of --available and --consumed such that only
738 the pool IDs are displayed. No labels or errors will be printed
739 if this option is specified.
740 REFRESH OPTIONS
743 The refresh command pulls the latest subscription data from the server.
744 Normally, the system polls the subscription management service at a set
745 interval (4 hours by default) to check for any changes in the available
746 subscriptions. The refresh command checks with the subscription manage‐
747 ment service right then, outside the normal interval. Use of the re‐
748 fresh command will clear caches related to the content access mode of
749 the system and allow the system to retrieve fresh data as necessary.
750 --force
753 Force regeneration of entitlement certificates on the server be‐
754 fore these certificates are pulled from the server.
755 ENVIRONMENTS OPTIONS
759 The environments command lists all of the environments that have been
760 configured for an organization. This command is only used for organiza‐
761 tions which have a locally-hosted subscription or content service of
762 some kind, like Subscription Asset Manager. The concept of environments
763 -- and therefore this command -- have no meaning for environments which
764 use the Customer Portal Subscription Management services.
765 --username=USERNAME
768 Gives the username for the account to use to connect to the or‐
769 ganization account.
770 --password=PASSWORD
773 Gives the user account password.
774 --token=TOKEN
777 Token to use when authorizing against the server.
778 --org=ORG
781 Identifies the organization for which to list the configured en‐
782 vironments.
783 REPOS OPTIONS
787 The repos command lists all of the repositories that are available to a
788 system. This command is only used for organizations which have a lo‐
789 cally-hosted content service of some kind, like Subscription Asset Man‐
790 ager. With Red Hat's hosted content service, there is only one central
791 repository.
792 --list Lists all of the repositories that are provided by the content
795 service used by the system.
796 --list-enabled
799 Lists all of the enabled repositories that are provided by the
800 content service used by the system.
801 --list-disabled
804 Lists all of the disabled repositories that are provided by the
805 content service used by the system.
806 --enable=REPO_ID
809 Enables the specified repository, which is made available by the
810 content sources identified in the system subscriptions. To en‐
811 able multiple repositories, use this argument multiple times.
812 Wild cards * and ? are supported. The repositories enabled by
813 this option and disabled by --disable are processed in the same
814 order they are specified.
815 --disable=REPO_ID
818 Disables the specified repository, which is made available by
819 the content sources identified in the system subscriptions. To
820 disable multiple repositories, use this argument multiple times.
821 Wild cards * and ? are supported. The repositories disabled by
822 this option and enabled by --enable are processed in the same
823 order they are specified.
824 ORGS OPTIONS
828 The orgs command lists all of the organizations which are available to
829 the specified user account. A multi-tenant infrastructure may have mul‐
830 tiple organizations within a single customer, and users may be re‐
831 stricted to access only a subset of the total number of organizations.
832 --username=USERNAME
835 Gives the username for the account to use to connect to the or‐
836 ganization account.
837 --password=PASSWORD
840 Gives the user account password.
841 --token=TOKEN
844 Token to use when authorizing against the server.
845 --serverurl=SERVER_HOSTNAME
848 Passes the name of the subscription service to use to list all
849 available organizations. The orgs command will list all organi‐
850 zations for the specified service for which the user account is
851 granted access. The default value, if this is not given, is the
852 Customer Portal Subscription Management service, https://sub‐
853 scription.rhsm.redhat.com:443. If there is an on-premise sub‐
854 scription service such as Subscription Asset Manager, this pa‐
855 rameter can be used to submit the hostname of the subscription
856 service, in the form [protocol://]servername[:port][/prefix].
857 For Subscription Asset Manager, if the Subscription Manager tool
858 is configured with the Subscription Asset Manager RPM, then the
859 default value for the --serverurl parameter is for the on-
860 premise Subscription Asset Manager server.
861 PLUGIN OPTIONS
865 The plugins command lists the available subscription-manager plugins.
866 --list List the available subscription-manager plugins.
869 --listslots
872 List the available plugin slots
873 --listhooks
876 List the available plugin slots and the hooks that handle them.
877 --verbose
880 Show additional info about the plugins, such as the plugin con‐
881 figuration values.
882 REPO-OVERRIDE OPTIONS
885 The repo-override command allows the user to manage custom content
886 repository settings
887 --repo The repository to modify (can be specified more than once)
890 --add=NAME:VALUE
893 Adds a named override with the provided value to repositories
894 specified with the --repo option
895 --remove=NAME
898 Removes a named override from the repositories specified with
899 the --repo option
900 --remove-all
903 Removes all overrides from repositories specified with the
904 --repo option
905 --list Lists all overrides from repositories specified with the --repo
908 option
909 IDENTITY OPTIONS
913 The identity command handles the UUID of a system, which identifies the
914 system to the subscription management service after registration. This
915 command can simply return the UUID or it can be used to restore the
916 registration of a previously-registered system to the subscription man‐
917 agement service.
918 --regenerate
921 Requests that the subscription management service issue a new
922 identity certificate for the system, using an existing UUID in
923 the original identity certificate. If this is used alone, then
924 the identity command also uses the original identity certificate
925 to bind to the subscription management service, using certifi‐
926 cate-based authentication.
927 --username=USERNAME
930 Gives the username for the account which is registering the sys‐
931 tem; this user account is usually tied to the user account for
932 the content delivery system which supplies the content. Op‐
933 tional, for user-based authentication.
934 --password=PASSWORD
937 Gives the user account password. Optional, for user-based au‐
938 thentication.
939 --token=TOKEN
942 Token to use when authorizing against the server.
943 --force
946 Regenerates the identity certificate for the system using user‐
947 name/password or token authentication. This is used with the
948 --regenerate option. --regenerate alone will use an existing
949 identity certificate to authenticate to the subscription manage‐
950 ment service. If the certificate is missing or corrupted or in
951 other circumstances, then it may be better to use user authenti‐
952 cation rather than certificate-based authentication. In that
953 case, the --force option requires the username or password or
954 token to be given either as an argument or in response to a
955 prompt.
956 FACTS OPTIONS
960 The facts command lists the system information, like the release ver‐
961 sion, number of CPUs, and other architecture information.
962 --list Lists the system information. These are simple attribute: value
965 pairs that reflect much of the information in the /etc/sysconfig
966 directory
967 cpu.architecture: x86_64
968 cpu.core(s)_per_socket: 1
969 cpu.cpu(s): 2
970 cpu.cpu_family: 6
971 cpu.cpu_mhz: 1861.776
972 cpu.cpu_op-mode(s): 64-bit
973 cpu.cpu_socket(s): 2
974 cpu.hypervisor_vendor: KVM
975 cpu.model: 2
976 cpu.numa_node(s): 1
977 cpu.numa_node0_cpu(s): 0,1
978 cpu.stepping: 3
979 cpu.thread(s)_per_core: 1
980 cpu.vendor_id: GenuineIntel
981 cpu.virtualization_type: full
982 distribution.id: Santiago
983 distribution.name: Red Hat Enterprise Linux Workstation
984 distribution.version: 6.1
985 ----
986 --update
990 Updates the system information. This is particularly important
991 whenever there is a hardware change (such as adding a CPU) or a
992 system upgrade because these changes can affect the subscrip‐
993 tions that are compatible with the system.
994 CLEAN OPTIONS
997 The clean command removes all of the subscription and identity data
998 from the local system without affecting the system information in the
999 subscription management service. This means that any of the subscrip‐
1000 tions applied to the system are not available for other systems to use.
1001 The clean command is useful in cases where the local subscription in‐
1002 formation is corrupted or lost somehow, and the system will be re-reg‐
1003 istered using the register --consumerid=EXISTING_ID command.
1004 This command has no options.
1007 CONFIG OPTIONS
1010 The config command changes the rhsm.conf configuration file used by
1011 Subscription Manager. Almost all of the connection information used by
1012 Subscription Manager to access the subscription management service,
1013 content server, and any proxies is set in the configuration file, as
1014 well as general configuration parameters like the frequency Subscrip‐
1015 tion Manager checks for subscriptions updates. There are major divi‐
1016 sions in the rhsm.conf file, such as [server] which is used to config‐
1017 ure the subscription management service. When changing the Subscription
1018 Manager configuration, the settings are identified with the format sec‐
1019 tion.name and then the new value. For example:
1020 server.hostname=newsubscription.example.com
1022 --list Prints the current configuration for Subscription Manager.
1025 --remove=section.name
1028 Deletes the current value for the parameter without supplying a
1029 new parameter. A blank value tells Subscription Manager to use
1030 service default values for that parameter. If there are no de‐
1031 faults, then the feature is ignored.
1032 --section.name=VALUE
1035 Sets a parameter to a new, specified value. This is commonly
1036 used for connection settings:
1037 * server.hostname (subscription management service)
1039 * server.proxy
1041 * server.proxy_port
1043 * server.proxy_user
1045 * server.proxy_password
1047 * rhsm.baseurl (content server)
1049 * rhsm.certFrequency
1051 VERSION OPTIONS
1054 The version command displays information about the current Subscription
1055 Manager package, the subscription service the system is registered to
1056 (if it is currently registered), and the subscription management server
1057 that the system is configured to use. For example:
1058 [root@server ~]# subscription-manager version
1060 server type: Red Hat Subscription Management
1061 subscription management server: 0.9.18-1
1062 subscription management rules: 5.9
1063 subscription-manager: 1.12.1-1.git.28.5cd97a5.fc20
1064 python-rhsm: 1.11.4-1.git.1.2f38ded.fc20
1065 This command has no options.
1068 STATUS OPTIONS
1072 The status command shows the current status of the products and at‐
1073 tached subscriptions for the system. If some products are not fully
1074 covered or subscriptions have expired, then the status command shows
1075 why subscriptions are not current and returns an error code.
1076 [root@server ~]# subscription-manager status
1078 +-------------------------------------------+
1079 System Status Details
1080 +-------------------------------------------+
1081 Overall Status: Current
1082 --ondate=DATE
1086 Shows the system status for a specific date in the future. The
1087 format of the date is YYYY-MM-DD.
1088 [root@server ~]# subscription-manager status --ondate=2014-01-01
1090 +-------------------------------------------+
1091 System Status Details
1092 +-------------------------------------------+
1093 Overall Status: Insufficient
1094 DEPRECATED COMMANDS
1097 As the structures of subscription configuration have changed, some of
1098 the original management commands have become obsolete. These commands
1099 have been replaced with updated commands.
1100 subscribe
1103 This has been replaced with attach. A similar registration op‐
1104 tion, --subscribe, has also be replaced with --auto-attach.
1105 unsubscribe
1108 This has been replaced with remove.
1109 activate
1112 This has been replaced with redeem.
1113 addons This has been replaced with syspurpose addons.
1116 role This has been replaced with syspurpose role.
1119 service-level
1122 This has been replaced with syspurpose service-level.
1123 usage This has been replaced with syspurpose usage.
1126
1129 subscription-manager has two major tasks:
1130 1. Handling the registration for a given system to a subscrip‐
1133 tion management service
1134 2. Handling the product subscriptions for installed products on
1137 a system
1138 subscription-manager makes it easier for network administrators to
1141 maintain parity between software subscriptions and updates and their
1142 installed products by tracking and managing what subscriptions are at‐
1143 tached to a system and when those subscriptions expire or are exceeded.
1144 REGISTERING AND UNREGISTERING MACHINES
1148 A system is either registered to a subscription management service --
1149 which makes all of the subscriptions available to the system -- or it
1150 is not registered. Unregistered systems necessarily lack valid software
1151 subscriptions because there is no way to record that the subscriptions
1152 have been used nor any way to renew them.
1153 The default subscription management service in the Subscription Manager
1156 configuration is the Customer Portal Subscription Management service.
1157 The configuration file can be edited before the system is registered to
1158 point to an on-premise subscription management service like Subscrip‐
1159 tion Asset Manager.
1160 Systems are usually registered to a subscription management service as
1163 part of their initial configuration, such as the kickstart process.
1164 However, systems can be registered manually after they are configured,
1165 can be removed from a content service, or re-registered.
1166 If a system has never been registered (not even during first boot),
1169 then the register command will register the system with whatever sub‐
1170 scription management service is configured in the /etc/rhsm/rhsm.conf
1171 file. This command requires, at a minimum, the username and password or
1172 token for an account to connect to the subscription management service.
1173 If the credentials aren't passed with the command, then subscription-
1174 manager prompts for the username and password interactively.
1175 When there is a single organization or when using the Customer Portal
1178 Subscription Management service, all that is required is the user‐
1179 name/password set or the token is used. For example:
1180 subscription-manager register --username=admin --password=secret or subscription-manager register --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo
1182 With on-premise subscription services, such as Subscription Asset Man‐
1185 ager, the infrastructure is more complex. The local administrator can
1186 define independent groups called organizations which represent physical
1187 or organizational divisions (--org). Those organizations can be subdi‐
1188 vided into environments (--environment). Optionally, the information
1189 about what subscription service (--serverurl) and content delivery net‐
1190 work (--baseurl) to use for the system registration can also be passed
1191 (which overrides the Red Hat Subscription Manager settings). The server
1192 and content URLs are usually configured in the Subscription Manager
1193 configuration before registering a system.
1194 subscription-manager register --username=admin --password=secret
1196 --org="IT Dept" --environment="local dev" --serverurl=local-cloudforms.example.com --baseurl=https://local-cloudforms.example.com:8088/cfFe
1197 If a system is in a multi-tenant environment and the organization is
1201 not provided with the registration request, registration fails with a
1202 remote server error. In the rhsm.log, there will be errors about being
1203 unable to load the owners interface.
1204 If a system is registered and then somehow its subscription information
1208 is lost -- a drive crashes or the certificates are deleted or corrupted
1209 -- the system can be re-registered, with all of its subscriptions re‐
1210 stored, by registering with the existing ID.
1211 subscription-manager register --username=admin
1213 --password=secret --consumerid=1234abcd
1214 A system uses an SSL client certificate (its identity certificate) to
1217 authenticate to the subscriptions system to check for updates or
1218 changes to subscriptions. If the identity certificate is lost or cor‐
1219 rupted, it can be regenerated using the identity command.
1220 subscription-manager identity --regenerate
1222 Using the --force option will prompt for the username and password for
1225 the account, if one isn't given, and then return the new inventory ID
1226 and the hostname of the registered system.
1227 subscription-manager identity --force
1229 Username: jsmith
1230 Password:
1231 eff9a4c9-3579-49e5-a52f-83f2db29ab52 server.example.com
1232 A system is unregistered and removed from the subscription management
1236 service simply by running the unregister command. Unregistering a sys‐
1237 tem and removing its attached subscriptions can free up subscriptions
1238 when a system is taken offline or moved to a different department.
1239 subscription-manager unregister
1241 An option with registration, --auto-attach, will automatically attach
1244 the subscriptions pool which best matches the system architecture and
1245 configuration to the newly-registered system. This option attaches sub‐
1246 scriptions as part of the registration process, rather than separately
1247 managing subscriptions.
1248 subscription-manager register --username=admin --password=secret
1250 --auto-attach
1251 Auto-attach also supports an option to set a preferred service level
1254 with the selected subscriptions, the --servicelevel option. In this
1255 case, the --servicelevel option sets a preference that helps the auto-
1256 attach process select appropriate subscriptions. For example, if the
1257 preferred service level for a production server is premium, and there
1258 are three matching subscriptions with different service levels (none,
1259 standard, and premium), the auto-attach process selects the subscrip‐
1260 tion which offers a premium service level.
1261 subscription-manager register --username=admin --password=secret
1263 --auto-attach --servicelevel=premium
1264 LISTING, ATTACHING, AND REMOVING SUBSCRIPTIONS FOR PRODUCTS
1267 A subscription is essentially the right to install, use, and receive
1268 updates for a Red Hat product. (Sometimes multiple individual software
1269 products are bundled together into a single subscription.) When a sys‐
1270 tem is registered, the subscription management service is aware of the
1271 system and has a list of all of the possible product subscriptions that
1272 the system can install and use. A subscription is applied to a system
1273 when the system is attached to the subscription pool that makes that
1274 product available. A system releases or removes that subscription
1275 (meaning, it removes that subscription so that another system can use
1276 that subscription count).
1277 list command shows you what subscriptions are available specifically to
1280 the system (meaning subscriptions which are active, have available
1281 quantities, and match the hardware and architecture) or all subscrip‐
1282 tions for the organization. Using the --ondate option shows subscrip‐
1283 tions that are or will be active at a specific time (otherwise, it
1284 shows subscriptions which are active today).
1285 subscription-manager list --available --ondate=2012-01-31
1287 +-------------------------------------------+
1288 Available Subscriptions
1289 +-------------------------------------------+
1290 Subscription Name: Red Hat Enterprise Linux
1291 SKU: SYS0395
1292 Pool Id: 8a85f981302cbaf201302d899adf05a9
1293 Quantity: 249237
1294 Service Level: None
1295 Service Type: None
1296 Multi-Entitlement: No
1297 Starts: 01/01/2021
1298 Ends: 01/01/2022
1299 Machine Type: physical
1300 The list command can also be used to show what products you currently
1303 have installed, as a way of tracking what products you have versus what
1304 subscriptions you have on the system.
1305 subscription-manager list --installed
1307 +-------------------------------------------+
1309 Installed Product Status
1310 +-------------------------------------------+
1311 ProductName: Red Hat Enterprise Linux Server
1313 Product ID: 69
1314 Version: 6.3
1315 Arch: x86_64
1316 Status: Subscribed
1317 Started: 07/26/2012
1318 Ends: 08/31/2015
1319 The list can be filtered to only include products or subscriptions that
1322 match the query string provided to --matches option.
1323 subscription-manager list --installed --matches="*Server*"
1325 +-------------------------------------------+
1327 Installed Product Status
1328 +-------------------------------------------+
1329 ProductName: Red Hat Enterprise Linux Server
1331 Product ID: 69
1332 Version: 6.3
1333 Arch: x86_64
1334 Status: Subscribed
1335 Started: 07/26/2012
1336 Ends: 08/31/2015
1337 Attaching a subscription requires the ID for the subscription pool (the
1340 --pool option). For example:
1341 subscription-manager attach
1343 --pool=ff8080812bc382e3012bc3845da100d2
1344 As with the register command, the system can be auto-attached to the
1346 best-fitting subscriptions. This is the default action and is equiva‐
1347 lent to using the --auto option:
1348 subscription-manager attach
1350 Auto-attach also supports an option to set a preferred service level
1354 with the selected subscriptions, the --servicelevel option. In this
1355 case, the --servicelevel option sets a preference that helps the auto-
1356 attach process select appropriate subscriptions. For example, if the
1357 preferred service level for a production server is premium, and there
1358 are three matching subscriptions with different service levels (none,
1359 standard, and premium), the auto-attach process selects the subscrip‐
1360 tion which offers a premium subscription.
1361 subscription-manager attach --servicelevel=premium
1363 Some subscriptions define a count based on attributes of the system it‐
1366 self, like the number of sockets or the number of virtual guests on a
1367 host. You can combine multiple subscriptions together to cover the
1368 count. For example, if there is a four socket server, you can use two
1369 subscriptions for "RHEL Server for Two Sockets" to cover the socket
1370 count. To specify the number of subscriptions to use, use the --quan‐
1371 tity option. For example:
1372 subscription-manager attach
1374 --pool=ff8080812bc382e3012bc3845da100d2
1375 --quantity=2
1376 Removing subscription from a system releases the subscription back into
1379 the pool. The system remains registered with the subscription manage‐
1380 ment service. Each product has an identifying X.509 certificate in‐
1381 stalled with it. To remove a subscription for a specific product, spec‐
1382 ify the serial number (or numbers, in multiple --serial options) of the
1383 certificate:
1384 subscription-manager remove --serial=1128750306742160
1386 Giving the remove command with the --all option removes every subscrip‐
1389 tion the system has used.
1390 REDEEMING EXISTING SUBSCRIPTIONS
1394 Sometimes, a system may come preconfigured with products and subscrip‐
1395 tions. Rather than attaching a pool and claiming a subscription, this
1396 system simply needs to redeem its existing subscriptions.
1397 After registration, subscriptions on preconfigured systems can be
1400 claimed using the redeem command, which essentially auto-attaches the
1401 system to its preexisting subscriptions.
1402 subscription-manager redeem --email=admin@example.com --org="IT Dept"
1404 VIEWING LOCAL SUBSCRIPTION & CONTENT PROVIDER INFORMATION
1407 Red Hat has a hosted environment, through the Customer Portal, that
1408 provides centralized access to subscription management and content
1409 repositories. However, organizations can use other tools -- like Sub‐
1410 scription Manager -- for content hosting and subscription management.
1411 With a local content provider, the organization, environments, reposi‐
1412 tories, and other structural configuration is performed in the content
1413 provider. Red Hat Subscription Manager can be used to display this in‐
1414 formation, using the environments, orgs, and repos commands.
1415 subscription-manager repos --list
1417 subscription-manager environments --username=jsmith
1419 --password=secret --org=prod
1420 or
1422 subscription-manager environments --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo --org=prod
1424 subscription-manager orgs --username=jsmith
1427 --password=secret
1428 or
1430 subscription-manager orgs --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo
1432 CHANGING SUBSCRIPTION MANAGER CONFIGURATION
1435 The Subscription Manager CLI and GUI both use the /etc/rhsm/rhsm.conf
1436 file for configuration, including what content and subscription manage‐
1437 ment services to use and management settings like auto-attaching. This
1438 configuration file can be edited directly, or it can be edited using
1439 the config command. Parameters and values are passed as arguments with
1440 the config command in the format --section.parameter=value , where sec‐
1441 tion is the configuration section in the file: server, rhsm, rhsmcertd
1442 or logging.
1443 For example, to change the hostname of the subscription management ser‐
1446 vice host:
1447 subscription-manager config --server.hostname=myserver.example.com
1449 The entries in the logging section are somewhat special. The keys in
1452 this section are a name of a logger. The values are the logging level.
1453 Valid levels are one of: DEBUG , INFO , WARNING , ERROR , or CRITICAL
1455 Valid logger names are the full module path of any Subscription Manager
1457 module. For example: subscription_manager or subscription_manager.man‐
1458 agercli
1459 There are three main top-level loggers: subscription_manager, rhsm, and
1462 rhsm-app. All logger names begin with one of the above.
1463 To set the default log level for all loggers (that are not otherwise
1466 set in the logging section), edit the default_log_level key in
1467 /etc/rhsm/rhsm.conf
1468 UPDATING FACTS
1472 The information about a system, such as its hardware and CPU, its oper‐
1473 ating system versions, and memory, are collected by Subscription Man‐
1474 ager in a list of facts. Subscription Manager uses these facts to de‐
1475 termine what purchased subscriptions are compatible with the system.
1476 Whenever these facts change (such as installing an additional CPU), the
1477 facts can be updated immediately using the facts command.
1478 subscription-manager facts --update
1480 The collected facts can also be overridden by creating a JSON file in
1482 the /etc/rhsm/facts/ directory. These have simple formats that define a
1483 fact and value:
1484 {"fact1": "value1","fact2": "value2"}
1486 Any fact override file must have a .facts extension.
1489 When these fact files are added, running the facts command will update
1492 the collected facts with the new, manual facts or values.
1493 SUBSCRIPTIONS AND KICKSTART
1496 The subscription-manager tool can be run as a post-install script as
1497 part of the kickstart installation process. This allows subscription
1498 management (registering and applying subscriptions) to be automated
1499 along with installation. For example:
1500 %post --log=/root/ks-post.log
1502 /usr/sbin/subscription-manager register --username admin --password secret --org 'east colo' --auto-attach --servicelevel=premium --force
1503
1506 The subscription-manager tool uses outgoing HTTPS requests. In the de‐
1507 fault configuration it will use HTTPS on port 443 to the subscription
1508 servers subscription.rhsm.redhat.com and to the content delivery ser‐
1509 vice cdn.redhat.com.
1510 For information about the network addresses that subscription-manager
1512 and the subscription-manager yum plugin use see https://access.red‐
1513 hat.com/site/solutions/59586
1514
1517 subscription-manager can be configured to use a proxy in several ways:
1518 * via standard HTTP_PROXY , HTTPS_PROXY , NO_PROXY environment
1520 variables (environment-level settings)
1521 * via options in /etc/rhsm/rhsm.conf (application-level set‐
1523 tings)
1524 * via command-line arguments (command-level overrides)
1526 Although subscription-manager respects environment variables for proxy
1529 configuration, this should be avoided in favor of the configuration
1530 file, because the daemons (ex. rhsmcertd ) do not provide ways to mod‐
1531 ify their environments.
1532 Each option of the proxy configuration (hostname, port, host/domain
1534 pattern blocklist, username, password) is read independently, with
1535 precedence being command-line over configuration over environment, and
1536 then the resulting set of options is used to configure the proxy con‐
1537 figuration.
1538 For example, if the HTTP_PROXY environment variable is set and no_proxy
1540 is set in /etc/rhsm/rhsm.conf then both are present in the effective
1541 proxy configuration.
1542 If two equivalent options are set in different places, then the prece‐
1544 dence determines which value is effective.
1545 For example, the NO_PROXY environment variable is set and the no_proxy
1547 configuration file option is set, then the value from the configuration
1548 file is the effective value.
1549
1552 Default log location of the subscription-manager is
1553 /var/log/rhsm/rhsm.log. When the program is run under non-root user
1554 (e.g. as dnf plugin) the logs are written to
1555 $XDG_CACHE_HOME/rhsm/rhsm.log.
1556 If the directory isn't writable, the logs are printed to stderr.
1558
1561 * /etc/pki/consumer/*.pem
1562 * /etc/pki/entitlement/<serial>.pem
1564 * /etc/pki/product/*.pem
1566 * /etc/rhsm/rhsm.conf
1568 * /etc/rhsm/facts/*.facts
1570 * /var/log/rhsm/rhsm.log
1572
1575 Deon Lackey, <dlackey@redhat.com>, and Pradeep Kilambi, <pkilambi@red‐
1576 hat.com>
1577 subscription-manager(8)