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 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 1. register
93 2. unregister
96 3. attach
99 4. auto-attach
102 5. remove
105 6. release
108 7. import
111 8. redeem
114 9. list
117 10. refresh
120 11. environments
123 12. repos
126 13. orgs
129 14. plugins
132 15. identity
135 16. facts
138 17. clean
141 18. config
144 19. version
147 20. status
150 21. syspurpose
153 22. repo-override
156 Following commands were deprecated: addons, role, service-level, sub‐
159 scribe, unsubscribe, usage, and activate
160 COMMON OPTIONS
163 -h, --help
164 Prints the specific help information for the given command.
165 --proxy=PROXY
168 Uses an HTTP proxy. The PROXY name has the format hostname:port.
169 --proxyuser=PROXYUSERNAME
173 Gives the username to use to authenticate to the HTTP proxy.
174 --proxypass=PROXYPASSWORD
177 Gives the password to use to authenticate to the HTTP proxy.
178 --noproxy=NOPROXY
181 Specifies a list of domain suffixes which should bypass the HTTP
182 proxy.
183 --no-progress-messages
186 Disables progress messages that are being displayed when waiting
187 for server response.
188 REGISTER OPTIONS
191 The register command registers a new system to the subscription manage‐
192 ment service.
193 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 --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 --password=PASSWORD
208 Gives the user account password.
209 --token=TOKEN
212 Token to use when authorizing against the server.
213 --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 --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 --name=SYSTEM_NAME
245 Sets the name of the system to register. This defaults to the
246 hostname.
247 --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 --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 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 For example:
271 subscription-manager register --org="IT Dept" --activationkey=1234abcd
272 --auto-attach
275 Automatically attaches compatible subscriptions to this system.
276 --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 --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 --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 --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 --release=VERSION
322 Shortcut for "release --set=VERSION"
323 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 This command has no options.
335 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 --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 --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 --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 --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 --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 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 --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 --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 --show Shows whether auto-attach is enabled on the systems.
402 REMOVE OPTIONS
405 The remove command removes a subscription from the system. (This does
406 not uninstall the associated products.)
407 --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 --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 --all Removes all of the subscriptions attached to a system.
424 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 --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 --set=RELEASE
440 Sets the minor (Y-stream) release version to use, such as 6.3.
441 --unset
444 Removes any previously set release version preference.
445 SYSPURPOSE OPTIONS
449 The syspurpose command displays the current configured syspurpose pref‐
450 erences for the system.
451 The syspurpose command has subcommands for all the various syspurpose
454 preferences and attributes:
455 1. addons
458 2. role
461 3. service-level
464 4. usage
467 --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 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 --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 --list Lists the available addons system purpose values.
491 --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 --password=PASSWORD
499 Gives the user account password [Usable with --list on unregis‐
500 tered systems].
501 --token=TOKEN
504 Token to use when authorizing against the server [Usable with
505 --list on unregistered systems].
506 --org=ORG
509 Identifies the organization for which the addons apply [Usable
510 with --list on unregistered systems].
511 --add=ADDON
514 Addon to add to the list of requested addons for this system
515 --remove=ADDON
518 Remove the addon from the list of requested addons.
519 --unset
522 Removes all addons from the list of requested addons.
523 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 --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 --list Lists the available role system purpose values.
539 --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 --password=PASSWORD
547 Gives the user account password [Usable with --list on unregis‐
548 tered systems].
549 --token=TOKEN
552 Token to use when authorizing against the server [Usable with
553 --list on unregistered systems].
554 --org=ORG
557 Identifies the organization for which the role applies [Usable
558 with --list on unregistered systems].
559 --set=ROLE
562 Role to apply to this system
563 --unset
566 Removes any previously set role preference.
567 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 --serverurl=SERVER_URL
579 Server URL in the form of https://hostname:port/prefix [Usable
580 on unregistered systems].
581 --insecure
584 Do not check the server SSL certificate against available cer‐
585 tificate authorities
586 --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 --list Lists the available service levels.
594 --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 --password=PASSWORD
602 Gives the user account password [Usable with --list on unregis‐
603 tered systems].
604 --token=TOKEN
607 Token to use when authorizing against the server [Usable with
608 --list on unregistered systems].
609 --set=SERVICE_LEVEL
612 Service level to apply to this system
613 --unset
616 Removes any previously set service-level preference.
617 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 --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 --list Lists the available usage system purpose values.
632 --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 --password=PASSWORD
640 Gives the user account password [Usable with --list on unregis‐
641 tered systems].
642 --token=TOKEN
645 Token to use when authorizing against the server [Usable with
646 --list on unregistered systems].
647 --org=ORG
650 Identifies the organization for which the usage applies [Usable
651 with --list on unregistered systems].
652 --set=USAGE
655 Usage to apply to this system
656 --unset
659 Removes any previously set usage preference.
660 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 --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 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 --email=EMAIL
686 Gives the email account to send the redemption notification mes‐
687 sage to.
688 --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 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 --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 --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 --available
714 Lists available subscriptions which are not yet attached to the
715 system.
716 --consumed
719 Lists all of the subscriptions currently attached to the system.
720 --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 --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 --no-overlap
737 Shows pools which provide products that are not already covered;
738 only used with --available option.
739 --match-installed
742 Shows only subscriptions matching products that are currently
743 installed; only used with --available option.
744 --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 --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 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 --force
775 Force regeneration of entitlement certificates on the server be‐
776 fore these certificates are pulled from the server.
777 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 --username=USERNAME
790 Gives the username for the account to use to connect to the or‐
791 ganization account.
792 --password=PASSWORD
795 Gives the user account password.
796 --token=TOKEN
799 Token to use when authorizing against the server.
800 --org=ORG
803 Identifies the organization for which to list the configured en‐
804 vironments.
805 --list Lists all of the environments that have been configured for an
808 organization.
809 --list-enabled
812 Lists the environments in the order that they have been enabled
813 for this consumer.
814 --list-disabled
817 Lists all of the environments that have been configured for an
818 organization but not enabled for this consumer.
819 --set=SET
822 Sets an ordered list of one or more comma-separated environments
823 for this consumer.
824 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 --list Lists all of the repositories that are provided by the content
836 service used by the system.
837 --list-enabled
840 Lists all of the enabled repositories that are provided by the
841 content service used by the system.
842 --list-disabled
845 Lists all of the disabled repositories that are provided by the
846 content service used by the system.
847 --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 --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 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 --username=USERNAME
876 Gives the username for the account to use to connect to the or‐
877 ganization account.
878 --password=PASSWORD
881 Gives the user account password.
882 --token=TOKEN
885 Token to use when authorizing against the server.
886 --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 PLUGIN OPTIONS
906 The plugins command lists the available subscription-manager plugins.
907 --list List the available subscription-manager plugins.
910 --listslots
913 List the available plugin slots
914 --listhooks
917 List the available plugin slots and the hooks that handle them.
918 --verbose
921 Show additional info about the plugins, such as the plugin con‐
922 figuration values.
923 REPO-OVERRIDE OPTIONS
926 The repo-override command allows the user to manage custom content
927 repository settings
928 --repo The repository to modify (can be specified more than once)
931 --add=NAME:VALUE
934 Adds a named override with the provided value to repositories
935 specified with the --repo option
936 --remove=NAME
939 Removes a named override from the repositories specified with
940 the --repo option
941 --remove-all
944 Removes all overrides from repositories specified with the
945 --repo option
946 --list Lists all overrides from repositories specified with the --repo
949 option
950 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 --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 --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 --password=PASSWORD
978 Gives the user account password. Optional, for user-based au‐
979 thentication.
980 --token=TOKEN
983 Token to use when authorizing against the server.
984 --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 FACTS OPTIONS
1001 The facts command lists the system information, like the release ver‐
1002 sion, number of CPUs, and other architecture information.
1003 --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 --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 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 This command has no options.
1048 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 server.hostname=newsubscription.example.com
1063 --list Prints the current configuration for Subscription Manager.
1066 --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 --section.name=VALUE
1076 Sets a parameter to a new, specified value. This is commonly
1077 used for connection settings:
1078 * server.hostname (subscription management service)
1080 * server.proxy
1082 * server.proxy_port
1084 * server.proxy_user
1086 * server.proxy_password
1088 * rhsm.baseurl (content server)
1090 * rhsm.certFrequency
1092 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 [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 This command has no options.
1109 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 [root@server ~]# subscription-manager status
1119 +-------------------------------------------+
1120 System Status Details
1121 +-------------------------------------------+
1122 Overall Status: Current
1123 --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 [root@server ~]# subscription-manager status --ondate=2014-01-01
1131 +-------------------------------------------+
1132 System Status Details
1133 +-------------------------------------------+
1134 Overall Status: Insufficient
1135 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 subscribe
1144 This has been replaced with attach. A similar registration op‐
1145 tion, --subscribe, has also be replaced with --auto-attach.
1146 unsubscribe
1149 This has been replaced with remove.
1150 activate
1153 This has been replaced with redeem.
1154 addons This has been replaced with syspurpose addons.
1157 role This has been replaced with syspurpose role.
1160 service-level
1163 This has been replaced with syspurpose service-level.
1164 usage This has been replaced with syspurpose usage.
1167
1170 subscription-manager has two major tasks:
1171 1. Handling the registration for a given system to a subscrip‐
1174 tion management service
1175 2. Handling the product subscriptions for installed products on
1178 a system
1179 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 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 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 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 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 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 subscription-manager register --username=admin --password=secret or subscription-manager register --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo
1223 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 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 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 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 subscription-manager register --username=admin
1254 --password=secret --consumerid=1234abcd
1255 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 subscription-manager identity --regenerate
1263 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 subscription-manager identity --force
1270 Username: jsmith
1271 Password:
1272 eff9a4c9-3579-49e5-a52f-83f2db29ab52 server.example.com
1273 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 subscription-manager unregister
1282 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 subscription-manager register --username=admin --password=secret
1291 --auto-attach
1292 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 subscription-manager register --username=admin --password=secret
1304 --auto-attach --servicelevel=premium
1305 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 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 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 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 subscription-manager list --installed
1348 +-------------------------------------------+
1350 Installed Product Status
1351 +-------------------------------------------+
1352 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 The list can be filtered to only include products or subscriptions that
1363 match the query string provided to --matches option.
1364 subscription-manager list --installed --matches="*Server*"
1366 +-------------------------------------------+
1368 Installed Product Status
1369 +-------------------------------------------+
1370 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 Attaching a subscription requires the ID for the subscription pool (the
1381 --pool option). For example:
1382 subscription-manager attach
1384 --pool=ff8080812bc382e3012bc3845da100d2
1385 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 subscription-manager attach
1391 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 subscription-manager attach --servicelevel=premium
1404 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 subscription-manager attach
1415 --pool=ff8080812bc382e3012bc3845da100d2
1416 --quantity=2
1417 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 subscription-manager remove --serial=1128750306742160
1427 Giving the remove command with the --all option removes every subscrip‐
1430 tion the system has used.
1431 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 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 subscription-manager redeem --email=admin@example.com --org="IT Dept"
1445 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 subscription-manager repos --list
1458 subscription-manager environments --username=jsmith
1460 --password=secret --org=prod
1461 or
1463 subscription-manager environments --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo --org=prod
1465 subscription-manager orgs --username=jsmith
1468 --password=secret
1469 or
1471 subscription-manager orgs --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo
1473 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 For example, to change the hostname of the subscription management ser‐
1487 vice host:
1488 subscription-manager config --server.hostname=myserver.example.com
1490 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 Valid levels are one of: DEBUG , INFO , WARNING , ERROR , or CRITICAL
1496 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 There are three main top-level loggers: subscription_manager, rhsm, and
1503 rhsm-app. All logger names begin with one of the above.
1504 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 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 subscription-manager facts --update
1521 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 {"fact1": "value1","fact2": "value2"}
1527 Any fact override file must have a .facts extension.
1530 When these fact files are added, running the facts command will update
1533 the collected facts with the new, manual facts or values.
1534 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 %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
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 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
1558 subscription-manager can be configured to use a proxy in several ways:
1559 * via standard HTTP_PROXY , HTTPS_PROXY , NO_PROXY environment
1561 variables (environment-level settings)
1562 * via options in /etc/rhsm/rhsm.conf (application-level set‐
1564 tings)
1565 * via command-line arguments (command-level overrides)
1567 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 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 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 If two equivalent options are set in different places, then the prece‐
1585 dence determines which value is effective.
1586 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
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 If the directory isn't writable, the logs are printed to stderr.
1599
1602 * /etc/pki/consumer/*.pem
1603 * /etc/pki/entitlement/<serial>.pem
1605 * /etc/pki/product/*.pem
1607 * /etc/rhsm/rhsm.conf
1609 * /etc/rhsm/facts/*.facts
1611 * /var/log/rhsm/rhsm.log
1613
1616 Deon Lackey, <dlackey@redhat.com>, and Pradeep Kilambi, <pkilambi@red‐
1617 hat.com>
1618 subscription-manager(8)