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 --no-progress-messages
180 Disables progress messages that are being displayed when waiting
181 for server response.
182 REGISTER OPTIONS
185 The register command registers a new system to the subscription manage‐
186 ment service.
187 --username=USERNAME
190 Gives the username for the account which is registering the sys‐
191 tem; this user account is usually tied to the user account for
192 the content delivery system which supplies the content. Op‐
193 tional, for user-based authentication.
194 --password=PASSWORD
197 Gives the user account password.
198 --token=TOKEN
201 Token to use when authorizing against the server.
202 --serverurl=SERVER_HOSTNAME
205 Passes the name of the subscription service with which to regis‐
206 ter the system. The default value, if this is not given, is the
207 Customer Portal Subscription Management service, subscrip‐
208 tion.rhsm.redhat.com. If there is an on-premise subscription
209 service such as Subscription Asset Manager, this parameter can
210 be used to submit the hostname of the subscription service. For
211 Subscription Asset Manager, if the Subscription Manager tool is
212 configured with the Subscription Asset Manager RPM, then the de‐
213 fault value for the --serverurl parameter is for the on-premise
214 Subscription Asset Manager server.
215 --baseurl=https://CONTENT_SERVICE:PORT/PREFIX
219 Passes the name of the content delivery service to configure the
220 yum service to use to pull down packages. If there is an on-
221 premise subscription service such as Subscription Asset Manager
222 or CloudForms System Engine, this parameter can be used to sub‐
223 mit the URL of the content repository, in the form
224 https://server_name:port/prefix. PREFIX in particular depends
225 on the service type. For example, https://sam.exam‐
226 ple.com:8088/sam is the baseurl for a SAM service.
227 https://sat6.example.com/pulp/repos is the baseurl for a Satel‐
228 lite 6 service with the hostname sat6.example.com .
229 https://cdn.redhat.com is the baseurl for the Red Hat CDN.
230 --name=SYSTEM_NAME
234 Sets the name of the system to register. This defaults to the
235 hostname.
236 --consumerid=CONSUMERID
240 References an existing system inventory ID to resume using a
241 previous registration for this system. The ID is used as an in‐
242 ventory number for the system in the subscription management
243 service database. If the system's identity is lost or corrupted,
244 this option allows it to resume using its previous identity and
245 subscriptions.
246 --activationkey=KEYS
249 Gives a comma-separated list of product keys to use to redeem or
250 apply specific subscriptions to the system. This is used for
251 preconfigured systems which may already have products installed.
252 Activation keys are issued by an on-premise subscription manage‐
253 ment service, such as Subscription Asset Manager.
254 When the --activationkey option is used, it is not necessary to
256 use the --username and --password options, because the authenti‐
257 cation information is implicit in the activation key.
258 For example:
260 subscription-manager register --org="IT Dept" --activationkey=1234abcd
261 --auto-attach
264 Automatically attaches compatible subscriptions to this system.
265 --servicelevel=LEVEL
269 Sets the preferred service level to use with subscriptions added
270 to the system. Service levels are commonly premium, standard,
271 and none, though other levels may be available depending on the
272 product and the contract.
273 --force
276 When the system is already registered, a new attempt to register
277 will fail with a message reminding the user that the system is
278 already registered. However, passing the --force, option will
279 implicitly attempt to unregister the system first. Beware that
280 the --force option does not guarantee a successful registration.
281 For example, if the registration with --force includes a differ‐
282 ent --serverurl than was used for the original registration, the
283 implicit call to unregister from the original entitlement server
284 will fail with invalid credentials and the registration with
285 force will be aborted. In this case, the user should explicitly
286 unregister from the original entitlement server. If unregister‐
287 ing is not possible, then running subscription-manager clean
288 will effectively abandon the original registration identity and
289 entitlements. Once cleaned, registering a new system identity
290 should succeed with or without force.
291 --org=ORG
294 Assigns the system to an organization. Infrastructures which are
295 managed on-site may be multi-tenant, meaning that there are mul‐
296 tiple organizations within one customer unit. A system may be
297 assigned manually to one of these organizations. When a system
298 is registered with the Customer Portal, this is not required.
299 When a system is registered with an on-premise application such
300 as Subscription Asset Manager, this argument is required, unless
301 there is only a single organization configured.
302 --environments=ENV
305 Registers the system to one or more environments within an orga‐
306 nization. This is a comma-separated list and the order is main‐
307 tained.
308 --release=VERSION
311 Shortcut for "release --set=VERSION"
312 UNREGISTER OPTIONS
315 The unregister command does two important things. Firstly, it will im‐
316 plicitly remove all of the currently attached subscriptions thereby re‐
317 turning the consumed quantity of entitlements back to their subscrip‐
318 tion pools making them available for other consumers. Secondly, it will
319 remove the system's consumer identity thereby removing its contact with
320 the currently configured subscription management service.
321 This command has no options.
324 ATTACH OPTIONS
327 The attach command applies a specific subscription to the system. This
328 command is not possible to use, when the content access mode of the or‐
329 ganization to which the system is registered is simple content access
330 mode.
331 --auto Automatically attaches the best-matched compatible subscription
334 or subscriptions to the system. This is the default unless
335 --pool or --file are used.
336 --pool=POOLID
339 Gives the ID for the subscriptions pool (collection of products)
340 to attach to the system. This overrides the default of --auto.
341 --file=FILE
344 Specifies a file from which to read whitespace-delimited pool
345 IDs. If FILE is "-", the pool IDs will be read from stdin. This
346 overrides the default of --auto.
347 --quantity=NUMBER
350 Attaches a specified number of subscriptions to the system. Sub‐
351 scriptions may have certain limits on them, like the number of
352 sockets on the system or the number of allowed virtual guests.
353 It is possible to attach multiple subscriptions (or stacking
354 subscriptions) to cover the number of sockets, guests, or other
355 characteristics. May not be used with an auto-attach.
356 --servicelevel=LEVEL
360 Sets the preferred service level to use with subscriptions auto‐
361 matically attached to the system. Service levels are commonly
362 premium, standard, and none, though other levels may be avail‐
363 able depending on the product and the contract. This option can‐
364 not be used when attaching specific pools via --pool or --file.
365 AUTO-ATTACH OPTIONS
368 The auto-attach command sets whether the ability to check, attach, and
369 update subscriptions occurs automatically on the system. Auto-attaching
370 subscriptions checks the currently-installed products, attached sub‐
371 scriptions, and any changes in available subscriptions every four hours
372 using the rhsmcertd daemon.
373 --enable
376 Enables the auto-attach option for the system. If there is any
377 change in the subscriptions for the system, any subscriptions
378 expire, or any new products are installed, then subscription-
379 manager detects the changes and automatically attaches the ap‐
380 propriate subscriptions so that the system remains covered.
381 --disable
384 Disables the auto-attach option for the system. If auto-attach
385 is disabled, then any changes in installed products or subscrip‐
386 tions for the system (including expired subscriptions) must be
387 addressed manually by the administrator.
388 --show Shows whether auto-attach is enabled on the systems.
391 REMOVE OPTIONS
394 The remove command removes a subscription from the system. (This does
395 not uninstall the associated products.)
396 --serial=SERIALNUMBER
399 Gives the serial number of the subscription certificate for the
400 specific product to remove from the system. Subscription cer‐
401 tificates attached to a system are in a certificate, in
402 /etc/pki/entitlement/<serial_number>.pem. To remove multiple
403 subscriptions, use the --serial option multiple times.
404 --pool=POOLID
407 Removes all subscription certificates for the specified pool id
408 from the system. To remove multiple sets of subscriptions, use
409 the --pool option multiple times.
410 --all Removes all of the subscriptions attached to a system.
413 RELEASE OPTIONS
417 The release command sets a sticky OS version to use when installing or
418 updating packages. This sets a preference for the minor version of the
419 OS, such as 6.2 or 6.3. This can prevent unplanned or unsupported oper‐
420 ating system version upgrades when an IT environment must maintain a
421 certified configuration.
422 --list Lists the available OS versions. If a release preference is not
425 set, then there is a message saying it is not set.
426 --set=RELEASE
429 Sets the minor (Y-stream) release version to use, such as 6.3.
430 --unset
433 Removes any previously set release version preference.
434 SYSPURPOSE OPTIONS
438 The syspurpose command displays the current configured syspurpose pref‐
439 erences for the system.
440 The syspurpose command has subcommands for all the various syspurpose
443 preferences and attributes:
444 1. addons
447 2. role
450 3. service-level
453 4. usage
456 --show Shows the system's current set of syspurpose preference format‐
460 ted as JSON. Single-valued entries for which there is no value
461 will be included in the output with a value of "". List entries
462 which have no value will be included in the output with a value
463 of "[]" (less the quotes).
464 addons options
468 The addons subcommand displays the current configured addons system
469 purpose attribute preference for products installed on the system. For
470 example, if the addons preference is ADDON1, then a subscription with a
471 ADDON1 addon is selected when auto-attaching subscriptions to the sys‐
472 tem.
473 --show Shows the system's current addons preference. If a addons is not
476 set, then there is a message saying it is not set.
477 --list Lists the available addons system purpose values.
480 --username=USERNAME
483 Gives the username for the account to use to connect to the or‐
484 ganization account [Usable with --list on unregistered systems].
485 --password=PASSWORD
488 Gives the user account password [Usable with --list on unregis‐
489 tered systems].
490 --token=TOKEN
493 Token to use when authorizing against the server [Usable with
494 --list on unregistered systems].
495 --org=ORG
498 Identifies the organization for which the addons apply [Usable
499 with --list on unregistered systems].
500 --add=ADDON
503 Addon to add to the list of requested addons for this system
504 --remove=ADDON
507 Remove the addon from the list of requested addons.
508 --unset
511 Removes all addons from the list of requested addons.
512 role options
516 The role subcommand displays the current configured role preference for
517 products installed on the system. For example, if the role preference
518 is "Red Hat Enterprise Linux Server", then a subscription with a "Red
519 Hat Enterprise Linux Server" role is selected when auto-attaching sub‐
520 scriptions to the system.
521 --show Shows the system's current role preference. If a role is not
524 set, then there is a message saying it is not set.
525 --list Lists the available role system purpose values.
528 --username=USERNAME
531 Gives the username for the account to use to connect to the or‐
532 ganization account [Usable with --list on unregistered systems].
533 --password=PASSWORD
536 Gives the user account password [Usable with --list on unregis‐
537 tered systems].
538 --token=TOKEN
541 Token to use when authorizing against the server [Usable with
542 --list on unregistered systems].
543 --org=ORG
546 Identifies the organization for which the role applies [Usable
547 with --list on unregistered systems].
548 --set=ROLE
551 Role to apply to this system
552 --unset
555 Removes any previously set role preference.
556 service-level options
560 The service-level subcommand displays the current configured service
561 level preference for products installed on the system. For example, if
562 the service-level preference is standard, then a subscription with a
563 standard service level is selected when auto-attaching subscriptions to
564 the system.
565 --serverurl=SERVER_URL
568 Server URL in the form of https://hostname:port/prefix [Usable
569 on unregistered systems].
570 --insecure
573 Do not check the server SSL certificate against available cer‐
574 tificate authorities
575 --show Shows the system's current service-level preference. If a ser‐
578 vice level is not set, then there is a message saying it is not
579 set.
580 --list Lists the available service levels.
583 --username=USERNAME
586 Gives the username for the account to use to connect to the or‐
587 ganization account [Usable with --list on unregistered systems].
588 --password=PASSWORD
591 Gives the user account password [Usable with --list on unregis‐
592 tered systems].
593 --token=TOKEN
596 Token to use when authorizing against the server [Usable with
597 --list on unregistered systems].
598 --set=SERVICE_LEVEL
601 Service level to apply to this system
602 --unset
605 Removes any previously set service-level preference.
606 usage options
610 The usage subcommand displays the current configured usage preference
611 for products installed on the system. For example, if the usage prefer‐
612 ence is "Production", then a subscription with a "Production" usage is
613 selected when auto-attaching subscriptions to the system.
614 --show Shows the system's current usage preference. If a usage is not
617 set, then there is a message saying it is not set.
618 --list Lists the available usage system purpose values.
621 --username=USERNAME
624 Gives the username for the account to use to connect to the or‐
625 ganization account [Usable with --list on unregistered systems].
626 --password=PASSWORD
629 Gives the user account password [Usable with --list on unregis‐
630 tered systems].
631 --token=TOKEN
634 Token to use when authorizing against the server [Usable with
635 --list on unregistered systems].
636 --org=ORG
639 Identifies the organization for which the usage applies [Usable
640 with --list on unregistered systems].
641 --set=USAGE
644 Usage to apply to this system
645 --unset
648 Removes any previously set usage preference.
649 IMPORT OPTIONS
653 The import command imports and applies a subscription certificate for
654 the system which was generated externally, such as in the Customer Por‐
655 tal, and then copied over to the system. Importing can be necessary if
656 a system is preconfigured in the subscription management service or if
657 it is offline or unable to access the subscription management service
658 but it has the proper, relevant subscriptions attached to the system.
659 --certificate=CERTIFICATE_FILE
662 Points to a certificate PEM file which contains the subscription
663 certificate. This can be used multiple times to import multiple
664 subscription certificates.
665 REDEEM OPTIONS
668 The redeem command is used for systems that are purchased from third-
669 party vendors that include a subscription. The redemption process es‐
670 sentially auto-attaches the preselected subscription that the vendor
671 supplied to the system.
672 --email=EMAIL
675 Gives the email account to send the redemption notification mes‐
676 sage to.
677 --locale=LOCALE
680 Sets the locale to use for the message. If none is given, then
681 it defaults to the local system's locale.
682 LIST OPTIONS
686 The list command lists all of the subscriptions that are compatible
687 with a system. The options allow the list to be filtered by subscrip‐
688 tions that are used by the system or unused subscriptions that are
689 available to the system.
690 --afterdate=YYYY-MM-DD
693 Shows pools that are active on or after the given date. This is
694 only used with the --available option.
695 --all Lists all possible subscriptions that have been purchased, even
698 if they don't match the architecture of the system. This is used
699 with the --available option.
700 --available
703 Lists available subscriptions which are not yet attached to the
704 system.
705 --consumed
708 Lists all of the subscriptions currently attached to the system.
709 --installed
712 Lists products which are currently installed on the system which
713 may (or may not) have subscriptions associated with them, as
714 well as products with attached subscriptions which may (or may
715 not) be installed. (default)
716 --ondate=YYYY-MM-DD
719 Sets the date to use to search for active and available sub‐
720 scriptions. The default (if not explicitly passed) is today's
721 date; using a later date looks for subscriptions which will be
722 active then. This is only used with the --available option.
723 --no-overlap
726 Shows pools which provide products that are not already covered;
727 only used with --available option.
728 --match-installed
731 Shows only subscriptions matching products that are currently
732 installed; only used with --available option.
733 --matches=SEARCH
736 Limits the output of --installed, --available and --consumed to
737 only subscriptions or products which contain SEARCH in the sub‐
738 scription or product information, varying with the list re‐
739 quested and the server version.
740 SEARCH may contain the wildcards ? or * to match a single char‐
741 acter or zero or more characters, respectively. The wildcard
742 characters may be escaped with a backslash to represent a lit‐
743 eral question mark or asterisk. Likewise, to represent a back‐
744 slash, it must be escaped with another backslash.
745 --pool-only
748 Limits the output of --available and --consumed such that only
749 the pool IDs are displayed. No labels or errors will be printed
750 if this option is specified.
751 REFRESH OPTIONS
754 The refresh command pulls the latest subscription data from the server.
755 Normally, the system polls the subscription management service at a set
756 interval (4 hours by default) to check for any changes in the available
757 subscriptions. The refresh command checks with the subscription manage‐
758 ment service right then, outside the normal interval. Use of the re‐
759 fresh command will clear caches related to the content access mode of
760 the system and allow the system to retrieve fresh data as necessary.
761 --force
764 Force regeneration of entitlement certificates on the server be‐
765 fore these certificates are pulled from the server.
766 ENVIRONMENTS OPTIONS
770 The environments command lists all of the environments that have been
771 configured for an organization. This command is only used for organiza‐
772 tions which have a locally-hosted subscription or content service of
773 some kind, like Subscription Asset Manager. The concept of environments
774 -- and therefore this command -- have no meaning for environments which
775 use the Customer Portal Subscription Management services.
776 --username=USERNAME
779 Gives the username for the account to use to connect to the or‐
780 ganization account.
781 --password=PASSWORD
784 Gives the user account password.
785 --token=TOKEN
788 Token to use when authorizing against the server.
789 --org=ORG
792 Identifies the organization for which to list the configured en‐
793 vironments.
794 --list Lists all of the environments that have been configured for an
797 organization.
798 --list-enabled
801 Lists the environments in the order that they have been enabled
802 for this consumer.
803 --list-disabled
806 Lists all of the environments that have been configured for an
807 organization but not enabled for this consumer.
808 --set=SET
811 Sets an ordered list of one or more comma-separated environments
812 for this consumer.
813 REPOS OPTIONS
817 The repos command lists all of the repositories that are available to a
818 system. This command is only used for organizations which have a lo‐
819 cally-hosted content service of some kind, like Subscription Asset Man‐
820 ager. With Red Hat's hosted content service, there is only one central
821 repository.
822 --list Lists all of the repositories that are provided by the content
825 service used by the system.
826 --list-enabled
829 Lists all of the enabled repositories that are provided by the
830 content service used by the system.
831 --list-disabled
834 Lists all of the disabled repositories that are provided by the
835 content service used by the system.
836 --enable=REPO_ID
839 Enables the specified repository, which is made available by the
840 content sources identified in the system subscriptions. To en‐
841 able multiple repositories, use this argument multiple times.
842 Wild cards * and ? are supported. The repositories enabled by
843 this option and disabled by --disable are processed in the same
844 order they are specified.
845 --disable=REPO_ID
848 Disables the specified repository, which is made available by
849 the content sources identified in the system subscriptions. To
850 disable multiple repositories, use this argument multiple times.
851 Wild cards * and ? are supported. The repositories disabled by
852 this option and enabled by --enable are processed in the same
853 order they are specified.
854 ORGS OPTIONS
858 The orgs command lists all of the organizations which are available to
859 the specified user account. A multi-tenant infrastructure may have mul‐
860 tiple organizations within a single customer, and users may be re‐
861 stricted to access only a subset of the total number of organizations.
862 --username=USERNAME
865 Gives the username for the account to use to connect to the or‐
866 ganization account.
867 --password=PASSWORD
870 Gives the user account password.
871 --token=TOKEN
874 Token to use when authorizing against the server.
875 --serverurl=SERVER_HOSTNAME
878 Passes the name of the subscription service to use to list all
879 available organizations. The orgs command will list all organi‐
880 zations for the specified service for which the user account is
881 granted access. The default value, if this is not given, is the
882 Customer Portal Subscription Management service, https://sub‐
883 scription.rhsm.redhat.com:443. If there is an on-premise sub‐
884 scription service such as Subscription Asset Manager, this pa‐
885 rameter can be used to submit the hostname of the subscription
886 service, in the form [protocol://]servername[:port][/prefix].
887 For Subscription Asset Manager, if the Subscription Manager tool
888 is configured with the Subscription Asset Manager RPM, then the
889 default value for the --serverurl parameter is for the on-
890 premise Subscription Asset Manager server.
891 PLUGIN OPTIONS
895 The plugins command lists the available subscription-manager plugins.
896 --list List the available subscription-manager plugins.
899 --listslots
902 List the available plugin slots
903 --listhooks
906 List the available plugin slots and the hooks that handle them.
907 --verbose
910 Show additional info about the plugins, such as the plugin con‐
911 figuration values.
912 REPO-OVERRIDE OPTIONS
915 The repo-override command allows the user to manage custom content
916 repository settings
917 --repo The repository to modify (can be specified more than once)
920 --add=NAME:VALUE
923 Adds a named override with the provided value to repositories
924 specified with the --repo option
925 --remove=NAME
928 Removes a named override from the repositories specified with
929 the --repo option
930 --remove-all
933 Removes all overrides from repositories specified with the
934 --repo option
935 --list Lists all overrides from repositories specified with the --repo
938 option
939 IDENTITY OPTIONS
943 The identity command handles the UUID of a system, which identifies the
944 system to the subscription management service after registration. This
945 command can simply return the UUID or it can be used to restore the
946 registration of a previously-registered system to the subscription man‐
947 agement service.
948 --regenerate
951 Requests that the subscription management service issue a new
952 identity certificate for the system, using an existing UUID in
953 the original identity certificate. If this is used alone, then
954 the identity command also uses the original identity certificate
955 to bind to the subscription management service, using certifi‐
956 cate-based authentication.
957 --username=USERNAME
960 Gives the username for the account which is registering the sys‐
961 tem; this user account is usually tied to the user account for
962 the content delivery system which supplies the content. Op‐
963 tional, for user-based authentication.
964 --password=PASSWORD
967 Gives the user account password. Optional, for user-based au‐
968 thentication.
969 --token=TOKEN
972 Token to use when authorizing against the server.
973 --force
976 Regenerates the identity certificate for the system using user‐
977 name/password or token authentication. This is used with the
978 --regenerate option. --regenerate alone will use an existing
979 identity certificate to authenticate to the subscription manage‐
980 ment service. If the certificate is missing or corrupted or in
981 other circumstances, then it may be better to use user authenti‐
982 cation rather than certificate-based authentication. In that
983 case, the --force option requires the username or password or
984 token to be given either as an argument or in response to a
985 prompt.
986 FACTS OPTIONS
990 The facts command lists the system information, like the release ver‐
991 sion, number of CPUs, and other architecture information.
992 --list Lists the system information. These are simple attribute: value
995 pairs that reflect much of the information in the /etc/sysconfig
996 directory
997 cpu.architecture: x86_64
998 cpu.core(s)_per_socket: 1
999 cpu.cpu(s): 2
1000 cpu.cpu_family: 6
1001 cpu.cpu_mhz: 1861.776
1002 cpu.cpu_op-mode(s): 64-bit
1003 cpu.cpu_socket(s): 2
1004 cpu.hypervisor_vendor: KVM
1005 cpu.model: 2
1006 cpu.numa_node(s): 1
1007 cpu.numa_node0_cpu(s): 0,1
1008 cpu.stepping: 3
1009 cpu.thread(s)_per_core: 1
1010 cpu.vendor_id: GenuineIntel
1011 cpu.virtualization_type: full
1012 distribution.id: Santiago
1013 distribution.name: Red Hat Enterprise Linux Workstation
1014 distribution.version: 6.1
1015 ----
1016 --update
1020 Updates the system information. This is particularly important
1021 whenever there is a hardware change (such as adding a CPU) or a
1022 system upgrade because these changes can affect the subscrip‐
1023 tions that are compatible with the system.
1024 CLEAN OPTIONS
1027 The clean command removes all of the subscription and identity data
1028 from the local system without affecting the system information in the
1029 subscription management service. This means that any of the subscrip‐
1030 tions applied to the system are not available for other systems to use.
1031 The clean command is useful in cases where the local subscription in‐
1032 formation is corrupted or lost somehow, and the system will be re-reg‐
1033 istered using the register --consumerid=EXISTING_ID command.
1034 This command has no options.
1037 CONFIG OPTIONS
1040 The config command changes the rhsm.conf configuration file used by
1041 Subscription Manager. Almost all of the connection information used by
1042 Subscription Manager to access the subscription management service,
1043 content server, and any proxies is set in the configuration file, as
1044 well as general configuration parameters like the frequency Subscrip‐
1045 tion Manager checks for subscriptions updates. There are major divi‐
1046 sions in the rhsm.conf file, such as [server] which is used to config‐
1047 ure the subscription management service. When changing the Subscription
1048 Manager configuration, the settings are identified with the format sec‐
1049 tion.name and then the new value. For example:
1050 server.hostname=newsubscription.example.com
1052 --list Prints the current configuration for Subscription Manager.
1055 --remove=section.name
1058 Deletes the current value for the parameter without supplying a
1059 new parameter. A blank value tells Subscription Manager to use
1060 service default values for that parameter. If there are no de‐
1061 faults, then the feature is ignored.
1062 --section.name=VALUE
1065 Sets a parameter to a new, specified value. This is commonly
1066 used for connection settings:
1067 * server.hostname (subscription management service)
1069 * server.proxy
1071 * server.proxy_port
1073 * server.proxy_user
1075 * server.proxy_password
1077 * rhsm.baseurl (content server)
1079 * rhsm.certFrequency
1081 VERSION OPTIONS
1084 The version command displays information about the current Subscription
1085 Manager package, the subscription service the system is registered to
1086 (if it is currently registered), and the subscription management server
1087 that the system is configured to use. For example:
1088 [root@server ~]# subscription-manager version
1090 server type: Red Hat Subscription Management
1091 subscription management server: 0.9.18-1
1092 subscription management rules: 5.9
1093 subscription-manager: 1.12.1-1.git.28.5cd97a5.fc20
1094 python-rhsm: 1.11.4-1.git.1.2f38ded.fc20
1095 This command has no options.
1098 STATUS OPTIONS
1102 The status command shows the current status of the products and at‐
1103 tached subscriptions for the system. If some products are not fully
1104 covered or subscriptions have expired, then the status command shows
1105 why subscriptions are not current and returns an error code.
1106 [root@server ~]# subscription-manager status
1108 +-------------------------------------------+
1109 System Status Details
1110 +-------------------------------------------+
1111 Overall Status: Current
1112 --ondate=DATE
1116 Shows the system status for a specific date in the future. The
1117 format of the date is YYYY-MM-DD.
1118 [root@server ~]# subscription-manager status --ondate=2014-01-01
1120 +-------------------------------------------+
1121 System Status Details
1122 +-------------------------------------------+
1123 Overall Status: Insufficient
1124 DEPRECATED COMMANDS
1127 As the structures of subscription configuration have changed, some of
1128 the original management commands have become obsolete. These commands
1129 have been replaced with updated commands.
1130 subscribe
1133 This has been replaced with attach. A similar registration op‐
1134 tion, --subscribe, has also be replaced with --auto-attach.
1135 unsubscribe
1138 This has been replaced with remove.
1139 activate
1142 This has been replaced with redeem.
1143 addons This has been replaced with syspurpose addons.
1146 role This has been replaced with syspurpose role.
1149 service-level
1152 This has been replaced with syspurpose service-level.
1153 usage This has been replaced with syspurpose usage.
1156
1159 subscription-manager has two major tasks:
1160 1. Handling the registration for a given system to a subscrip‐
1163 tion management service
1164 2. Handling the product subscriptions for installed products on
1167 a system
1168 subscription-manager makes it easier for network administrators to
1171 maintain parity between software subscriptions and updates and their
1172 installed products by tracking and managing what subscriptions are at‐
1173 tached to a system and when those subscriptions expire or are exceeded.
1174 REGISTERING AND UNREGISTERING MACHINES
1178 A system is either registered to a subscription management service --
1179 which makes all of the subscriptions available to the system -- or it
1180 is not registered. Unregistered systems necessarily lack valid software
1181 subscriptions because there is no way to record that the subscriptions
1182 have been used nor any way to renew them.
1183 The default subscription management service in the Subscription Manager
1186 configuration is the Customer Portal Subscription Management service.
1187 The configuration file can be edited before the system is registered to
1188 point to an on-premise subscription management service like Subscrip‐
1189 tion Asset Manager.
1190 Systems are usually registered to a subscription management service as
1193 part of their initial configuration, such as the kickstart process.
1194 However, systems can be registered manually after they are configured,
1195 can be removed from a content service, or re-registered.
1196 If a system has never been registered (not even during first boot),
1199 then the register command will register the system with whatever sub‐
1200 scription management service is configured in the /etc/rhsm/rhsm.conf
1201 file. This command requires, at a minimum, the username and password or
1202 token for an account to connect to the subscription management service.
1203 If the credentials aren't passed with the command, then subscription-
1204 manager prompts for the username and password interactively.
1205 When there is a single organization or when using the Customer Portal
1208 Subscription Management service, all that is required is the user‐
1209 name/password set or the token is used. For example:
1210 subscription-manager register --username=admin --password=secret or subscription-manager register --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo
1212 With on-premise subscription services, such as Subscription Asset Man‐
1215 ager, the infrastructure is more complex. The local administrator can
1216 define independent groups called organizations which represent physical
1217 or organizational divisions (--org). Those organizations can be subdi‐
1218 vided into environments (--environment). Optionally, the information
1219 about what subscription service (--serverurl) and content delivery net‐
1220 work (--baseurl) to use for the system registration can also be passed
1221 (which overrides the Red Hat Subscription Manager settings). The server
1222 and content URLs are usually configured in the Subscription Manager
1223 configuration before registering a system.
1224 subscription-manager register --username=admin --password=secret
1226 --org="IT Dept" --environment="local dev" --serverurl=local-cloudforms.example.com --baseurl=https://local-cloudforms.example.com:8088/cfFe
1227 If a system is in a multi-tenant environment and the organization is
1231 not provided with the registration request, registration fails with a
1232 remote server error. In the rhsm.log, there will be errors about being
1233 unable to load the owners interface.
1234 If a system is registered and then somehow its subscription information
1238 is lost -- a drive crashes or the certificates are deleted or corrupted
1239 -- the system can be re-registered, with all of its subscriptions re‐
1240 stored, by registering with the existing ID.
1241 subscription-manager register --username=admin
1243 --password=secret --consumerid=1234abcd
1244 A system uses an SSL client certificate (its identity certificate) to
1247 authenticate to the subscriptions system to check for updates or
1248 changes to subscriptions. If the identity certificate is lost or cor‐
1249 rupted, it can be regenerated using the identity command.
1250 subscription-manager identity --regenerate
1252 Using the --force option will prompt for the username and password for
1255 the account, if one isn't given, and then return the new inventory ID
1256 and the hostname of the registered system.
1257 subscription-manager identity --force
1259 Username: jsmith
1260 Password:
1261 eff9a4c9-3579-49e5-a52f-83f2db29ab52 server.example.com
1262 A system is unregistered and removed from the subscription management
1266 service simply by running the unregister command. Unregistering a sys‐
1267 tem and removing its attached subscriptions can free up subscriptions
1268 when a system is taken offline or moved to a different department.
1269 subscription-manager unregister
1271 An option with registration, --auto-attach, will automatically attach
1274 the subscriptions pool which best matches the system architecture and
1275 configuration to the newly-registered system. This option attaches sub‐
1276 scriptions as part of the registration process, rather than separately
1277 managing subscriptions.
1278 subscription-manager register --username=admin --password=secret
1280 --auto-attach
1281 Auto-attach also supports an option to set a preferred service level
1284 with the selected subscriptions, the --servicelevel option. In this
1285 case, the --servicelevel option sets a preference that helps the auto-
1286 attach process select appropriate subscriptions. For example, if the
1287 preferred service level for a production server is premium, and there
1288 are three matching subscriptions with different service levels (none,
1289 standard, and premium), the auto-attach process selects the subscrip‐
1290 tion which offers a premium service level.
1291 subscription-manager register --username=admin --password=secret
1293 --auto-attach --servicelevel=premium
1294 LISTING, ATTACHING, AND REMOVING SUBSCRIPTIONS FOR PRODUCTS
1297 A subscription is essentially the right to install, use, and receive
1298 updates for a Red Hat product. (Sometimes multiple individual software
1299 products are bundled together into a single subscription.) When a sys‐
1300 tem is registered, the subscription management service is aware of the
1301 system and has a list of all of the possible product subscriptions that
1302 the system can install and use. A subscription is applied to a system
1303 when the system is attached to the subscription pool that makes that
1304 product available. A system releases or removes that subscription
1305 (meaning, it removes that subscription so that another system can use
1306 that subscription count).
1307 list command shows you what subscriptions are available specifically to
1310 the system (meaning subscriptions which are active, have available
1311 quantities, and match the hardware and architecture) or all subscrip‐
1312 tions for the organization. Using the --ondate option shows subscrip‐
1313 tions that are or will be active at a specific time (otherwise, it
1314 shows subscriptions which are active today).
1315 subscription-manager list --available --ondate=2012-01-31
1317 +-------------------------------------------+
1318 Available Subscriptions
1319 +-------------------------------------------+
1320 Subscription Name: Red Hat Enterprise Linux
1321 SKU: SYS0395
1322 Pool Id: 8a85f981302cbaf201302d899adf05a9
1323 Quantity: 249237
1324 Service Level: None
1325 Service Type: None
1326 Multi-Entitlement: No
1327 Starts: 01/01/2021
1328 Ends: 01/01/2022
1329 Machine Type: physical
1330 The list command can also be used to show what products you currently
1333 have installed, as a way of tracking what products you have versus what
1334 subscriptions you have on the system.
1335 subscription-manager list --installed
1337 +-------------------------------------------+
1339 Installed Product Status
1340 +-------------------------------------------+
1341 ProductName: Red Hat Enterprise Linux Server
1343 Product ID: 69
1344 Version: 6.3
1345 Arch: x86_64
1346 Status: Subscribed
1347 Started: 07/26/2012
1348 Ends: 08/31/2015
1349 The list can be filtered to only include products or subscriptions that
1352 match the query string provided to --matches option.
1353 subscription-manager list --installed --matches="*Server*"
1355 +-------------------------------------------+
1357 Installed Product Status
1358 +-------------------------------------------+
1359 ProductName: Red Hat Enterprise Linux Server
1361 Product ID: 69
1362 Version: 6.3
1363 Arch: x86_64
1364 Status: Subscribed
1365 Started: 07/26/2012
1366 Ends: 08/31/2015
1367 Attaching a subscription requires the ID for the subscription pool (the
1370 --pool option). For example:
1371 subscription-manager attach
1373 --pool=ff8080812bc382e3012bc3845da100d2
1374 As with the register command, the system can be auto-attached to the
1376 best-fitting subscriptions. This is the default action and is equiva‐
1377 lent to using the --auto option:
1378 subscription-manager attach
1380 Auto-attach also supports an option to set a preferred service level
1384 with the selected subscriptions, the --servicelevel option. In this
1385 case, the --servicelevel option sets a preference that helps the auto-
1386 attach process select appropriate subscriptions. For example, if the
1387 preferred service level for a production server is premium, and there
1388 are three matching subscriptions with different service levels (none,
1389 standard, and premium), the auto-attach process selects the subscrip‐
1390 tion which offers a premium subscription.
1391 subscription-manager attach --servicelevel=premium
1393 Some subscriptions define a count based on attributes of the system it‐
1396 self, like the number of sockets or the number of virtual guests on a
1397 host. You can combine multiple subscriptions together to cover the
1398 count. For example, if there is a four socket server, you can use two
1399 subscriptions for "RHEL Server for Two Sockets" to cover the socket
1400 count. To specify the number of subscriptions to use, use the --quan‐
1401 tity option. For example:
1402 subscription-manager attach
1404 --pool=ff8080812bc382e3012bc3845da100d2
1405 --quantity=2
1406 Removing subscription from a system releases the subscription back into
1409 the pool. The system remains registered with the subscription manage‐
1410 ment service. Each product has an identifying X.509 certificate in‐
1411 stalled with it. To remove a subscription for a specific product, spec‐
1412 ify the serial number (or numbers, in multiple --serial options) of the
1413 certificate:
1414 subscription-manager remove --serial=1128750306742160
1416 Giving the remove command with the --all option removes every subscrip‐
1419 tion the system has used.
1420 REDEEMING EXISTING SUBSCRIPTIONS
1424 Sometimes, a system may come preconfigured with products and subscrip‐
1425 tions. Rather than attaching a pool and claiming a subscription, this
1426 system simply needs to redeem its existing subscriptions.
1427 After registration, subscriptions on preconfigured systems can be
1430 claimed using the redeem command, which essentially auto-attaches the
1431 system to its preexisting subscriptions.
1432 subscription-manager redeem --email=admin@example.com --org="IT Dept"
1434 VIEWING LOCAL SUBSCRIPTION & CONTENT PROVIDER INFORMATION
1437 Red Hat has a hosted environment, through the Customer Portal, that
1438 provides centralized access to subscription management and content
1439 repositories. However, organizations can use other tools -- like Sub‐
1440 scription Manager -- for content hosting and subscription management.
1441 With a local content provider, the organization, environments, reposi‐
1442 tories, and other structural configuration is performed in the content
1443 provider. Red Hat Subscription Manager can be used to display this in‐
1444 formation, using the environments, orgs, and repos commands.
1445 subscription-manager repos --list
1447 subscription-manager environments --username=jsmith
1449 --password=secret --org=prod
1450 or
1452 subscription-manager environments --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo --org=prod
1454 subscription-manager orgs --username=jsmith
1457 --password=secret
1458 or
1460 subscription-manager orgs --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo
1462 CHANGING SUBSCRIPTION MANAGER CONFIGURATION
1465 The Subscription Manager CLI and GUI both use the /etc/rhsm/rhsm.conf
1466 file for configuration, including what content and subscription manage‐
1467 ment services to use and management settings like auto-attaching. This
1468 configuration file can be edited directly, or it can be edited using
1469 the config command. Parameters and values are passed as arguments with
1470 the config command in the format --section.parameter=value , where sec‐
1471 tion is the configuration section in the file: server, rhsm, rhsmcertd
1472 or logging.
1473 For example, to change the hostname of the subscription management ser‐
1476 vice host:
1477 subscription-manager config --server.hostname=myserver.example.com
1479 The entries in the logging section are somewhat special. The keys in
1482 this section are a name of a logger. The values are the logging level.
1483 Valid levels are one of: DEBUG , INFO , WARNING , ERROR , or CRITICAL
1485 Valid logger names are the full module path of any Subscription Manager
1487 module. For example: subscription_manager or subscription_manager.man‐
1488 agercli
1489 There are three main top-level loggers: subscription_manager, rhsm, and
1492 rhsm-app. All logger names begin with one of the above.
1493 To set the default log level for all loggers (that are not otherwise
1496 set in the logging section), edit the default_log_level key in
1497 /etc/rhsm/rhsm.conf
1498 UPDATING FACTS
1502 The information about a system, such as its hardware and CPU, its oper‐
1503 ating system versions, and memory, are collected by Subscription Man‐
1504 ager in a list of facts. Subscription Manager uses these facts to de‐
1505 termine what purchased subscriptions are compatible with the system.
1506 Whenever these facts change (such as installing an additional CPU), the
1507 facts can be updated immediately using the facts command.
1508 subscription-manager facts --update
1510 The collected facts can also be overridden by creating a JSON file in
1512 the /etc/rhsm/facts/ directory. These have simple formats that define a
1513 fact and value:
1514 {"fact1": "value1","fact2": "value2"}
1516 Any fact override file must have a .facts extension.
1519 When these fact files are added, running the facts command will update
1522 the collected facts with the new, manual facts or values.
1523 SUBSCRIPTIONS AND KICKSTART
1526 The subscription-manager tool can be run as a post-install script as
1527 part of the kickstart installation process. This allows subscription
1528 management (registering and applying subscriptions) to be automated
1529 along with installation. For example:
1530 %post --log=/root/ks-post.log
1532 /usr/sbin/subscription-manager register --username admin --password secret --org 'east colo' --auto-attach --servicelevel=premium --force
1533
1536 The subscription-manager tool uses outgoing HTTPS requests. In the de‐
1537 fault configuration it will use HTTPS on port 443 to the subscription
1538 servers subscription.rhsm.redhat.com and to the content delivery ser‐
1539 vice cdn.redhat.com.
1540 For information about the network addresses that subscription-manager
1542 and the subscription-manager yum plugin use see https://access.red‐
1543 hat.com/site/solutions/59586
1544
1547 subscription-manager can be configured to use a proxy in several ways:
1548 * via standard HTTP_PROXY , HTTPS_PROXY , NO_PROXY environment
1550 variables (environment-level settings)
1551 * via options in /etc/rhsm/rhsm.conf (application-level set‐
1553 tings)
1554 * via command-line arguments (command-level overrides)
1556 Although subscription-manager respects environment variables for proxy
1559 configuration, this should be avoided in favor of the configuration
1560 file, because the daemons (ex. rhsmcertd ) do not provide ways to mod‐
1561 ify their environments.
1562 Each option of the proxy configuration (hostname, port, host/domain
1564 pattern blocklist, username, password) is read independently, with
1565 precedence being command-line over configuration over environment, and
1566 then the resulting set of options is used to configure the proxy con‐
1567 figuration.
1568 For example, if the HTTP_PROXY environment variable is set and no_proxy
1570 is set in /etc/rhsm/rhsm.conf then both are present in the effective
1571 proxy configuration.
1572 If two equivalent options are set in different places, then the prece‐
1574 dence determines which value is effective.
1575 For example, the NO_PROXY environment variable is set and the no_proxy
1577 configuration file option is set, then the value from the configuration
1578 file is the effective value.
1579
1582 Default log location of the subscription-manager is
1583 /var/log/rhsm/rhsm.log. When the program is run under non-root user
1584 (e.g. as dnf plugin) the logs are written to
1585 $XDG_CACHE_HOME/rhsm/rhsm.log.
1586 If the directory isn't writable, the logs are printed to stderr.
1588
1591 * /etc/pki/consumer/*.pem
1592 * /etc/pki/entitlement/<serial>.pem
1594 * /etc/pki/product/*.pem
1596 * /etc/rhsm/rhsm.conf
1598 * /etc/rhsm/facts/*.facts
1600 * /var/log/rhsm/rhsm.log
1602
1605 Deon Lackey, <dlackey@redhat.com>, and Pradeep Kilambi, <pkilambi@red‐
1606 hat.com>
1607 subscription-manager(8)