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. deprecated commands: addons, role, service-level, subscribe,
147 unsubscribe, usage, and activate
148 22. repo-override
151 COMMON OPTIONS
155 -h, --help
156 Prints the specific help information for the given command.
157 --proxy=PROXY
160 Uses an HTTP proxy. The PROXY name has the format hostname:port.
161 --proxyuser=PROXYUSERNAME
165 Gives the username to use to authenticate to the HTTP proxy.
166 --proxypass=PROXYPASSWORD
169 Gives the password to use to authenticate to the HTTP proxy.
170 --noproxy=NOPROXY
173 Specifies a list of domain suffixes which should bypass the HTTP
174 proxy.
175 REGISTER OPTIONS
178 The register command registers a new system to the subscription manage‐
179 ment service.
180 --username=USERNAME
183 Gives the username for the account which is registering the sys‐
184 tem; this user account is usually tied to the user account for
185 the content delivery system which supplies the content. Op‐
186 tional, for user-based authentication.
187 --password=PASSWORD
190 Gives the user account password.
191 --token=TOKEN
194 Token to use when authorizing against the server.
195 --serverurl=SERVER_HOSTNAME
198 Passes the name of the subscription service with which to regis‐
199 ter the system. The default value, if this is not given, is the
200 Customer Portal Subscription Management service, subscrip‐
201 tion.rhsm.redhat.com. If there is an on-premise subscription
202 service such as Subscription Asset Manager, this parameter can
203 be used to submit the hostname of the subscription service. For
204 Subscription Asset Manager, if the Subscription Manager tool is
205 configured with the Subscription Asset Manager RPM, then the de‐
206 fault value for the --serverurl parameter is for the on-premise
207 Subscription Asset Manager server.
208 --baseurl=https://CONTENT_SERVICE:PORT/PREFIX
212 Passes the name of the content delivery service to configure the
213 yum service to use to pull down packages. If there is an on-
214 premise subscription service such as Subscription Asset Manager
215 or CloudForms System Engine, this parameter can be used to sub‐
216 mit the URL of the content repository, in the form
217 https://server_name:port/prefix. PREFIX in particular depends
218 on the service type. For example, https://sam.exam‐
219 ple.com:8088/sam is the baseurl for a SAM service.
220 https://sat6.example.com/pulp/repos is the baseurl for a Satel‐
221 lite 6 service with the hostname sat6.example.com .
222 https://cdn.redhat.com is the baseurl for the Red Hat CDN.
223 --name=SYSTEM_NAME
227 Sets the name of the system to register. This defaults to the
228 hostname.
229 --consumerid=CONSUMERID
233 References an existing system inventory ID to resume using a
234 previous registration for this system. The ID is used as an in‐
235 ventory number for the system in the subscription management
236 service database. If the system's identity is lost or corrupted,
237 this option allows it to resume using its previous identity and
238 subscriptions.
239 --activationkey=KEYS
242 Gives a comma-separated list of product keys to use to redeem or
243 apply specific subscriptions to the system. This is used for
244 preconfigured systems which may already have products installed.
245 Activation keys are issued by an on-premise subscription manage‐
246 ment service, such as Subscription Asset Manager.
247 When the --activationkey option is used, it is not necessary to
249 use the --username and --password options, because the authenti‐
250 cation information is implicit in the activation key.
251 For example:
253 subscription-manager register --org="IT Dept" --activationkey=1234abcd
254 --auto-attach
257 Automatically attaches compatible subscriptions to this system.
258 --servicelevel=LEVEL
262 Sets the preferred service level to use with subscriptions added
263 to the system. Service levels are commonly premium, standard,
264 and none, though other levels may be available depending on the
265 product and the contract.
266 --force
269 When the system is already registered, a new attempt to register
270 will fail with a message reminding the user that the system is
271 already registered. However, passing the --force, option will
272 implicitly attempt to unregister the system first. Beware that
273 the --force option does not guarantee a successful registration.
274 For example, if the registration with --force includes a differ‐
275 ent --serverurl than was used for the original registration, the
276 implicit call to unregister from the original entitlement server
277 will fail with invalid credentials and the registration with
278 force will be aborted. In this case, the user should explicitly
279 unregister from the original entitlement server. If unregister‐
280 ing is not possible, then running subscription-manager clean
281 will effectively abandon the original registration identity and
282 entitlements. Once cleaned, registering a new system identity
283 should succeed with or without force.
284 --org=ORG
287 Assigns the system to an organization. Infrastructures which are
288 managed on-site may be multi-tenant, meaning that there are mul‐
289 tiple organizations within one customer unit. A system may be
290 assigned manually to one of these organizations. When a system
291 is registered with the Customer Portal, this is not required.
292 When a system is registered with an on-premise application such
293 as Subscription Asset Manager, this argument is required, unless
294 there is only a single organization configured.
295 --environment=ENV
298 Registers the system to an environment within an organization.
299 --release=VERSION
302 Shortcut for "release --set=VERSION"
303 UNREGISTER OPTIONS
306 The unregister command does two important things. Firstly, it will im‐
307 plicitly remove all of the currently attached subscriptions thereby re‐
308 turning the consumed quantity of entitlements back to their subscrip‐
309 tion pools making them available for other consumers. Secondly, it will
310 remove the system's consumer identity thereby removing its contact with
311 the currently configured subscription management service.
312 This command has no options.
315 ATTACH OPTIONS
318 The attach command applies a specific subscription to the system.
319 --auto Automatically attaches the best-matched compatible subscription
322 or subscriptions to the system. This is the default unless
323 --pool or --file are used.
324 --pool=POOLID
327 Gives the ID for the subscriptions pool (collection of products)
328 to attach to the system. This overrides the default of --auto.
329 --file=FILE
332 Specifies a file from which to read whitespace-delimited pool
333 IDs. If FILE is "-", the pool IDs will be read from stdin. This
334 overrides the default of --auto.
335 --quantity=NUMBER
338 Attaches a specified number of subscriptions to the system. Sub‐
339 scriptions may have certain limits on them, like the number of
340 sockets on the system or the number of allowed virtual guests.
341 It is possible to attach multiple subscriptions (or stacking
342 subscriptions) to cover the number of sockets, guests, or other
343 characteristics. May not be used with an auto-attach.
344 --servicelevel=LEVEL
348 Sets the preferred service level to use with subscriptions auto‐
349 matically attached to the system. Service levels are commonly
350 premium, standard, and none, though other levels may be avail‐
351 able depending on the product and the contract. This option can‐
352 not be used when attaching specific pools via --pool or --file.
353 AUTO-ATTACH OPTIONS
356 The auto-attach command sets whether the ability to check, attach, and
357 update subscriptions occurs automatically on the system. Auto-attaching
358 subscriptions checks the currently-installed products, attached sub‐
359 scriptions, and any changes in available subscriptions every four hours
360 using the rhsmcertd daemon.
361 --enable
364 Enables the auto-attach option for the system. If there is any
365 change in the subscriptions for the system, any subscriptions
366 expire, or any new products are installed, then subscription-
367 manager detects the changes and automatically attaches the ap‐
368 propriate subscriptions so that the system remains covered.
369 --disable
372 Disables the auto-attach option for the system. If auto-attach
373 is disabled, then any changes in installed products or subscrip‐
374 tions for the system (including expired subscriptions) must be
375 addressed manually by the administrator.
376 --show Shows whether auto-attach is enabled on the systems.
379 REMOVE OPTIONS
382 The remove command removes a subscription from the system. (This does
383 not uninstall the associated products.)
384 --serial=SERIALNUMBER
387 Gives the serial number of the subscription certificate for the
388 specific product to remove from the system. Subscription cer‐
389 tificates attached to a system are in a certificate, in
390 /etc/pki/entitlement/<serial_number>.pem. To remove multiple
391 subscriptions, use the --serial option multiple times.
392 --pool=POOLID
395 Removes all subscription certificates for the specified pool id
396 from the system. To remove multiple sets of subscriptions, use
397 the --pool option multiple times.
398 --all Removes all of the subscriptions attached to a system.
401 RELEASE OPTIONS
405 The release command sets a sticky OS version to use when installing or
406 updating packages. This sets a preference for the minor version of the
407 OS, such as 6.2 or 6.3. This can prevent unplanned or unsupported oper‐
408 ating system version upgrades when an IT environment must maintain a
409 certified configuration.
410 --list Lists the available OS versions. If a release preference is not
413 set, then there is a message saying it is not set.
414 --set=RELEASE
417 Sets the minor (Y-stream) release version to use, such as 6.3.
418 --unset
421 Removes any previously set release version preference.
422 SYSPURPOSE OPTIONS
426 The syspurpose command displays the current configured syspurpose pref‐
427 erences for the system.
428 The syspurpose command has subcommands for all the various syspurpose
431 preferences and attributes:
432 1. addons
435 2. role
438 3. service-level
441 4. usage
444 --show Shows the system's current set of syspurpose preference format‐
448 ted as JSON. Single-valued entries for which there is no value
449 will be included in the output with a value of "". List entries
450 which have no value will be included in the output with a value
451 of "[]" (less the quotes).
452 addons options
456 The addons subcommand displays the current configured addons system
457 purpose attribute preference for products installed on the system. For
458 example, if the addons preference is ADDON1, then a subscription with a
459 ADDON1 addon is selected when auto-attaching subscriptions to the sys‐
460 tem.
461 --show Shows the system's current addons preference. If a addons is not
464 set, then there is a message saying it is not set.
465 --list Lists the available addons system purpose values.
468 --username=USERNAME
471 Gives the username for the account to use to connect to the or‐
472 ganization account [Use with --list when unregistered].
473 --password=PASSWORD
476 Gives the user account password [Use with --list when unregis‐
477 tered].
478 --token=TOKEN
481 Token to use when authorizing against the server [Use with
482 --list when unregistered].
483 --add=ADDON
486 Addon to add to the list of requested addons for this system
487 --remove=ADDON
490 Remove the addon from the list of requested addons.
491 --unset
494 Removes all addons from the list of requested addons.
495 --org=ORG
498 Identifies the organization for which the addons applies.
499 role options
503 The role subcommand displays the current configured role preference for
504 products installed on the system. For example, if the role preference
505 is "Red Hat Enterprise Linux Server", then a subscription with a "Red
506 Hat Enterprise Linux Server" role is selected when auto-attaching sub‐
507 scriptions to the system.
508 --show Shows the system's current role preference. If a role is not
511 set, then there is a message saying it is not set.
512 --list Lists the available role system purpose values.
515 --username=USERNAME
518 Gives the username for the account to use to connect to the or‐
519 ganization account [Use with --list when unregistered].
520 --password=PASSWORD
523 Gives the user account password [Use with --list when unregis‐
524 tered].
525 --token=TOKEN
528 Token to use when authorizing against the server [Use with
529 --list when unregistered].
530 --set=ROLE
533 Role to apply to this system
534 --unset
537 Removes any previously set role preference.
538 --org=ORG
541 Identifies the organization for which the role applies.
542 service-level options
546 The service-level subcommand displays the current configured service
547 level preference for products installed on the system. For example, if
548 the service-level preference is standard, then a subscription with a
549 standard service level is selected when auto-attaching subscriptions to
550 the system.
551 --serverurl=SERVER_URL
554 Server URL in the form of https://hostname:port/prefix
555 --insecure
558 Do not check the server SSL certificate against available cer‐
559 tificate authorities
560 --show Shows the system's current service-level preference. If a ser‐
563 vice level is not set, then there is a message saying it is not
564 set.
565 --list Lists the available service levels.
568 --username=USERNAME
571 Gives the username for the account to use to connect to the or‐
572 ganization account [Use with --list when unregistered].
573 --password=PASSWORD
576 Gives the user account password [Use with --list when unregis‐
577 tered].
578 --token=TOKEN
581 Token to use when authorizing against the server [Use with
582 --list when unregistered].
583 --set=SERVICE_LEVEL
586 Service level to apply to this system
587 --unset
590 Removes any previously set service-level preference.
591 usage options
595 The usage subcommand displays the current configured usage preference
596 for products installed on the system. For example, if the usage prefer‐
597 ence is "Production", then a subscription with a "Production" usage is
598 selected when auto-attaching subscriptions to the system.
599 --show Shows the system's current usage preference. If a usage is not
602 set, then there is a message saying it is not set.
603 --list Lists the available usage system purpose values.
606 --username=USERNAME
609 Gives the username for the account to use to connect to the or‐
610 ganization account [Use with --list when unregistered].
611 --password=PASSWORD
614 Gives the user account password [Use with --list when unregis‐
615 tered].
616 --token=TOKEN
619 Token to use when authorizing against the server [Use with
620 --list when unregistered].
621 --set=USAGE
624 Usage to apply to this system
625 --unset
628 Removes any previously set usage preference.
629 --org=ORG
632 Identifies the organization for which the usage applies.
633 IMPORT OPTIONS
637 The import command imports and applies a subscription certificate for
638 the system which was generated externally, such as in the Customer Por‐
639 tal, and then copied over to the system. Importing can be necessary if
640 a system is preconfigured in the subscription management service or if
641 it is offline or unable to access the subscription management service
642 but it has the proper, relevant subscriptions attached to the system.
643 --certificate=CERTIFICATE_FILE
646 Points to a certificate PEM file which contains the subscription
647 certificate. This can be used multiple times to import multiple
648 subscription certificates.
649 REDEEM OPTIONS
652 The redeem command is used for systems that are purchased from third-
653 party vendors that include a subscription. The redemption process es‐
654 sentially auto-attaches the preselected subscription that the vendor
655 supplied to the system.
656 --email=EMAIL
659 Gives the email account to send the redemption notification mes‐
660 sage to.
661 --locale=LOCALE
664 Sets the locale to use for the message. If none is given, then
665 it defaults to the local system's locale.
666 LIST OPTIONS
670 The list command lists all of the subscriptions that are compatible
671 with a system. The options allow the list to be filtered by subscrip‐
672 tions that are used by the system or unused subscriptions that are
673 available to the system.
674 --afterdate=YYYY-MM-DD
677 Shows pools that are active on or after the given date. This is
678 only used with the --available option.
679 --all Lists all possible subscriptions that have been purchased, even
682 if they don't match the architecture of the system. This is used
683 with the --available option.
684 --available
687 Lists available subscriptions which are not yet attached to the
688 system.
689 --consumed
692 Lists all of the subscriptions currently attached to the system.
693 --installed
696 Lists products which are currently installed on the system which
697 may (or may not) have subscriptions associated with them, as
698 well as products with attached subscriptions which may (or may
699 not) be installed. (default)
700 --ondate=YYYY-MM-DD
703 Sets the date to use to search for active and available sub‐
704 scriptions. The default (if not explicitly passed) is today's
705 date; using a later date looks for subscriptions which will be
706 active then. This is only used with the --available option.
707 --no-overlap
710 Shows pools which provide products that are not already covered;
711 only used with --available option.
712 --match-installed
715 Shows only subscriptions matching products that are currently
716 installed; only used with --available option.
717 --matches=SEARCH
720 Limits the output of --installed, --available and --consumed to
721 only subscriptions or products which contain SEARCH in the sub‐
722 scription or product information, varying with the list re‐
723 quested and the server version.
724 SEARCH may contain the wildcards ? or * to match a single char‐
725 acter or zero or more characters, respectively. The wildcard
726 characters may be escaped with a backslash to represent a lit‐
727 eral question mark or asterisk. Likewise, to represent a back‐
728 slash, it must be escaped with another backslash.
729 --pool-only
732 Limits the output of --available and --consumed such that only
733 the pool IDs are displayed. No labels or errors will be printed
734 if this option is specified.
735 REFRESH OPTIONS
738 The refresh command pulls the latest subscription data from the server.
739 Normally, the system polls the subscription management service at a set
740 interval (4 hours by default) to check for any changes in the available
741 subscriptions. The refresh command checks with the subscription manage‐
742 ment service right then, outside the normal interval. Use of the re‐
743 fresh command will clear caches related to the content access mode of
744 the system and allow the system to retrieve fresh data as necessary.
745 --force
748 Force regeneration of entitlement certificates on the server be‐
749 fore these certificates are pulled from the server.
750 ENVIRONMENTS OPTIONS
754 The environments command lists all of the environments that have been
755 configured for an organization. This command is only used for organiza‐
756 tions which have a locally-hosted subscription or content service of
757 some kind, like Subscription Asset Manager. The concept of environments
758 -- and therefore this command -- have no meaning for environments which
759 use the Customer Portal Subscription Management services.
760 --username=USERNAME
763 Gives the username for the account to use to connect to the or‐
764 ganization account.
765 --password=PASSWORD
768 Gives the user account password.
769 --token=TOKEN
772 Token to use when authorizing against the server.
773 --org=ORG
776 Identifies the organization for which to list the configured en‐
777 vironments.
778 REPOS OPTIONS
782 The repos command lists all of the repositories that are available to a
783 system. This command is only used for organizations which have a lo‐
784 cally-hosted content service of some kind, like Subscription Asset Man‐
785 ager. With Red Hat's hosted content service, there is only one central
786 repository.
787 --list Lists all of the repositories that are provided by the content
790 service used by the system.
791 --list-enabled
794 Lists all of the enabled repositories that are provided by the
795 content service used by the system.
796 --list-disabled
799 Lists all of the disabled repositories that are provided by the
800 content service used by the system.
801 --enable=REPO_ID
804 Enables the specified repository, which is made available by the
805 content sources identified in the system subscriptions. To en‐
806 able multiple repositories, use this argument multiple times.
807 Wild cards * and ? are supported.
808 --disable=REPO_ID
811 Disables the specified repository, which is made available by
812 the content sources identified in the system subscriptions. To
813 disable multiple repositories, use this argument multiple times.
814 Wild cards * and ? are supported.
815 ORGS OPTIONS
819 The orgs command lists all of the organizations which are available to
820 the specified user account. A multi-tenant infrastructure may have mul‐
821 tiple organizations within a single customer, and users may be re‐
822 stricted to access only a subset of the total number of organizations.
823 --username=USERNAME
826 Gives the username for the account to use to connect to the or‐
827 ganization account.
828 --password=PASSWORD
831 Gives the user account password.
832 --token=TOKEN
835 Token to use when authorizing against the server.
836 --serverurl=SERVER_HOSTNAME
839 Passes the name of the subscription service to use to list all
840 available organizations. The orgs command will list all organi‐
841 zations for the specified service for which the user account is
842 granted access. The default value, if this is not given, is the
843 Customer Portal Subscription Management service, https://sub‐
844 scription.rhsm.redhat.com:443. If there is an on-premise sub‐
845 scription service such as Subscription Asset Manager, this pa‐
846 rameter can be used to submit the hostname of the subscription
847 service, in the form [protocol://]servername[:port][/prefix].
848 For Subscription Asset Manager, if the Subscription Manager tool
849 is configured with the Subscription Asset Manager RPM, then the
850 default value for the --serverurl parameter is for the on-
851 premise Subscription Asset Manager server.
852 PLUGIN OPTIONS
856 The plugins command lists the available subscription-manager plugins.
857 --list List the available subscription-manager plugins.
860 --listslots
863 List the available plugin slots
864 --listhooks
867 List the available plugin slots and the hooks that handle them.
868 --verbose
871 Show additional info about the plugins, such as the plugin con‐
872 figuration values.
873 REPO-OVERRIDE OPTIONS
876 The repo-override command allows the user to manage custom content
877 repository settings
878 --repo The repository to modify (can be specified more than once)
881 --add=NAME:VALUE
884 Adds a named override with the provided value to repositories
885 specified with the --repo option
886 --remove=NAME
889 Removes a named override from the repositories specified with
890 the --repo option
891 --remove-all
894 Removes all overrides from repositories specified with the
895 --repo option
896 --list Lists all overrides from repositories specified with the --repo
899 option
900 IDENTITY OPTIONS
904 The identity command handles the UUID of a system, which identifies the
905 system to the subscription management service after registration. This
906 command can simply return the UUID or it can be used to restore the
907 registration of a previously-registered system to the subscription man‐
908 agement service.
909 --regenerate
912 Requests that the subscription management service issue a new
913 identity certificate for the system, using an existing UUID in
914 the original identity certificate. If this is used alone, then
915 the identity command also uses the original identity certificate
916 to bind to the subscription management service, using certifi‐
917 cate-based authentication.
918 --username=USERNAME
921 Gives the username for the account which is registering the sys‐
922 tem; this user account is usually tied to the user account for
923 the content delivery system which supplies the content. Op‐
924 tional, for user-based authentication.
925 --password=PASSWORD
928 Gives the user account password. Optional, for user-based au‐
929 thentication.
930 --token=TOKEN
933 Token to use when authorizing against the server.
934 --force
937 Regenerates the identity certificate for the system using user‐
938 name/password or token authentication. This is used with the
939 --regenerate option. --regenerate alone will use an existing
940 identity certificate to authenticate to the subscription manage‐
941 ment service. If the certificate is missing or corrupted or in
942 other circumstances, then it may be better to use user authenti‐
943 cation rather than certificate-based authentication. In that
944 case, the --force option requires the username or password or
945 token to be given either as an argument or in response to a
946 prompt.
947 FACTS OPTIONS
951 The facts command lists the system information, like the release ver‐
952 sion, number of CPUs, and other architecture information.
953 --list Lists the system information. These are simple attribute: value
956 pairs that reflect much of the information in the /etc/sysconfig
957 directory
958 cpu.architecture: x86_64
959 cpu.core(s)_per_socket: 1
960 cpu.cpu(s): 2
961 cpu.cpu_family: 6
962 cpu.cpu_mhz: 1861.776
963 cpu.cpu_op-mode(s): 64-bit
964 cpu.cpu_socket(s): 2
965 cpu.hypervisor_vendor: KVM
966 cpu.model: 2
967 cpu.numa_node(s): 1
968 cpu.numa_node0_cpu(s): 0,1
969 cpu.stepping: 3
970 cpu.thread(s)_per_core: 1
971 cpu.vendor_id: GenuineIntel
972 cpu.virtualization_type: full
973 distribution.id: Santiago
974 distribution.name: Red Hat Enterprise Linux Workstation
975 distribution.version: 6.1
976 ----
977 --update
981 Updates the system information. This is particularly important
982 whenever there is a hardware change (such as adding a CPU) or a
983 system upgrade because these changes can affect the subscrip‐
984 tions that are compatible with the system.
985 CLEAN OPTIONS
988 The clean command removes all of the subscription and identity data
989 from the local system without affecting the system information in the
990 subscription management service. This means that any of the subscrip‐
991 tions applied to the system are not available for other systems to use.
992 The clean command is useful in cases where the local subscription in‐
993 formation is corrupted or lost somehow, and the system will be re-reg‐
994 istered using the register --consumerid=EXISTING_ID command.
995 This command has no options.
998 CONFIG OPTIONS
1001 The config command changes the rhsm.conf configuration file used by
1002 Subscription Manager. Almost all of the connection information used by
1003 Subscription Manager to access the subscription management service,
1004 content server, and any proxies is set in the configuration file, as
1005 well as general configuration parameters like the frequency Subscrip‐
1006 tion Manager checks for subscriptions updates. There are major divi‐
1007 sions in the rhsm.conf file, such as [server] which is used to config‐
1008 ure the subscription management service. When changing the Subscription
1009 Manager configuration, the settings are identified with the format sec‐
1010 tion.name and then the new value. For example:
1011 server.hostname=newsubscription.example.com
1013 --list Prints the current configuration for Subscription Manager.
1016 --remove=section.name
1019 Deletes the current value for the parameter without supplying a
1020 new parameter. A blank value tells Subscription Manager to use
1021 service default values for that parameter. If there are no de‐
1022 faults, then the feature is ignored.
1023 --section.name=VALUE
1026 Sets a parameter to a new, specified value. This is commonly
1027 used for connection settings:
1028 * server.hostname (subscription management service)
1030 * server.proxy
1032 * server.proxy_port
1034 * server.proxy_user
1036 * server.proxy_password
1038 * rhsm.baseurl (content server)
1040 * rhsm.certFrequency
1042 VERSION OPTIONS
1045 The version command displays information about the current Subscription
1046 Manager package, the subscription service the system is registered to
1047 (if it is currently registered), and the subscription management server
1048 that the system is configured to use. For example:
1049 [root@server ~]# subscription-manager version
1051 server type: Red Hat Subscription Management
1052 subscription management server: 0.9.18-1
1053 subscription management rules: 5.9
1054 subscription-manager: 1.12.1-1.git.28.5cd97a5.fc20
1055 python-rhsm: 1.11.4-1.git.1.2f38ded.fc20
1056 This command has no options.
1059 STATUS OPTIONS
1063 The status command shows the current status of the products and at‐
1064 tached subscriptions for the system. If some products are not fully
1065 covered or subscriptions have expired, then the status command shows
1066 why subscriptions are not current and returns an error code.
1067 [root@server ~]# subscription-manager status
1069 +-------------------------------------------+
1070 System Status Details
1071 +-------------------------------------------+
1072 Overall Status: Current
1073 --ondate=DATE
1077 Shows the system status for a specific date in the future. The
1078 format of the date is YYYY-MM-DD.
1079 [root@server ~]# subscription-manager status --ondate=2014-01-01
1081 +-------------------------------------------+
1082 System Status Details
1083 +-------------------------------------------+
1084 Overall Status: Insufficient
1085 DEPRECATED COMMANDS
1088 As the structures of subscription configuration have changed, some of
1089 the original management commands have become obsolete. These commands
1090 have been replaced with updated commands.
1091 subscribe
1094 This has been replaced with attach. A similar registration op‐
1095 tion, --subscribe, has also be replaced with --auto-attach.
1096 unsubscribe
1099 This has been replaced with remove.
1100 activate
1103 This has been replaced with redeem.
1104 addons This has been replaced with syspurpose addons.
1107 role This has been replaced with syspurpose role.
1110 service-level
1113 This has been replaced with syspurpose service-level.
1114 usage This has been replaced with syspurpose usage.
1117
1120 subscription-manager has two major tasks:
1121 1. Handling the registration for a given system to a subscrip‐
1124 tion management service
1125 2. Handling the product subscriptions for installed products on
1128 a system
1129 subscription-manager makes it easier for network administrators to
1132 maintain parity between software subscriptions and updates and their
1133 installed products by tracking and managing what subscriptions are at‐
1134 tached to a system and when those subscriptions expire or are exceeded.
1135 REGISTERING AND UNREGISTERING MACHINES
1139 A system is either registered to a subscription management service --
1140 which makes all of the subscriptions available to the system -- or it
1141 is not registered. Unregistered systems necessarily lack valid software
1142 subscriptions because there is no way to record that the subscriptions
1143 have been used nor any way to renew them.
1144 The default subscription management service in the Subscription Manager
1147 configuration is the Customer Portal Subscription Management service.
1148 The configuration file can be edited before the system is registered to
1149 point to an on-premise subscription management service like Subscrip‐
1150 tion Asset Manager.
1151 Systems are usually registered to a subscription management service as
1154 part of their initial configuration, such as the firstboot or kickstart
1155 process. However, systems can be registered manually after they are
1156 configured, can be removed from a content service, or re-registered.
1157 If a system has never been registered (not even during firstboot), then
1160 the register command will register the system with whatever subscrip‐
1161 tion management service is configured in the /etc/rhsm/rhsm.conf file.
1162 This command requires, at a minimum, the username and password or token
1163 for an account to connect to the subscription management service. If
1164 the credentials aren't passed with the command, then subscription-man‐
1165 ager prompts for the username and password interactively.
1166 When there is a single organization or when using the Customer Portal
1169 Subscription Management service, all that is required is the user‐
1170 name/password set or the token is used. For example:
1171 subscription-manager register --username=admin --password=secret or subscription-manager register --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo
1173 With on-premise subscription services, such as Subscription Asset Man‐
1176 ager, the infrastructure is more complex. The local administrator can
1177 define independent groups called organizations which represent physical
1178 or organizational divisions (--org). Those organizations can be subdi‐
1179 vided into environments (--environment). Optionally, the information
1180 about what subscription service (--serverurl) and content delivery net‐
1181 work (--baseurl) to use for the system registration can also be passed
1182 (which overrides the Red Hat Subscription Manager settings). The server
1183 and content URLs are usually configured in the Subscription Manager
1184 configuration before registering a system.
1185 subscription-manager register --username=admin --password=secret
1187 --org="IT Dept" --environment="local dev" --serverurl=local-cloudforms.example.com --baseurl=https://local-cloudforms.example.com:8088/cfFe
1188 If a system is in a multi-tenant environment and the organization is
1192 not provided with the registration request, registration fails with a
1193 remote server error. In the rhsm.log, there will be errors about being
1194 unable to load the owners interface.
1195 If a system is registered and then somehow its subscription information
1199 is lost -- a drive crashes or the certificates are deleted or corrupted
1200 -- the system can be re-registered, with all of its subscriptions re‐
1201 stored, by registering with the existing ID.
1202 subscription-manager register --username=admin
1204 --password=secret --consumerid=1234abcd
1205 A system uses an SSL client certificate (its identity certificate) to
1208 authenticate to the subscriptions system to check for updates or
1209 changes to subscriptions. If the identity certificate is lost or cor‐
1210 rupted, it can be regenerated using the identity command.
1211 subscription-manager identity --regenerate
1213 Using the --force option will prompt for the username and password for
1216 the account, if one isn't given, and then return the new inventory ID
1217 and the hostname of the registered system.
1218 subscription-manager identity --force
1220 Username: jsmith
1221 Password:
1222 eff9a4c9-3579-49e5-a52f-83f2db29ab52 server.example.com
1223 A system is unregistered and removed from the subscription management
1227 service simply by running the unregister command. Unregistering a sys‐
1228 tem and removing its attached subscriptions can free up subscriptions
1229 when a system is taken offline or moved to a different department.
1230 subscription-manager unregister
1232 An option with registration, --auto-attach, will automatically attach
1235 the subscriptions pool which best matches the system architecture and
1236 configuration to the newly-registered system. This option attaches sub‐
1237 scriptions as part of the registration process, rather than separately
1238 managing subscriptions.
1239 subscription-manager register --username=admin --password=secret
1241 --auto-attach
1242 Auto-attach also supports an option to set a preferred service level
1245 with the selected subscriptions, the --servicelevel option. In this
1246 case, the --servicelevel option sets a preference that helps the auto-
1247 attach process select appropriate subscriptions. For example, if the
1248 preferred service level for a production server is premium, and there
1249 are three matching subscriptions with different service levels (none,
1250 standard, and premium), the auto-attach process selects the subscrip‐
1251 tion which offers a premium service level.
1252 subscription-manager register --username=admin --password=secret
1254 --auto-attach --servicelevel=premium
1255 LISTING, ATTACHING, AND REMOVING SUBSCRIPTIONS FOR PRODUCTS
1258 A subscription is essentially the right to install, use, and receive
1259 updates for a Red Hat product. (Sometimes multiple individual software
1260 products are bundled together into a single subscription.) When a sys‐
1261 tem is registered, the subscription management service is aware of the
1262 system and has a list of all of the possible product subscriptions that
1263 the system can install and use. A subscription is applied to a system
1264 when the system is attached to the subscription pool that makes that
1265 product available. A system releases or removes that subscription
1266 (meaning, it removes that subscription so that another system can use
1267 that subscription count).
1268 list command shows you what subscriptions are available specifically to
1271 the system (meaning subscriptions which are active, have available
1272 quantities, and match the hardware and architecture) or all subscrip‐
1273 tions for the organization. Using the --ondate option shows subscrip‐
1274 tions that are or will be active at a specific time (otherwise, it
1275 shows subscriptions which are active today).
1276 subscription-manager list --available --ondate=2012-01-31
1278 +-------------------------------------------+
1279 Available Subscriptions
1280 +-------------------------------------------+
1281 Subscription Name: Red Hat Enterprise Linux
1282 SKU: SYS0395
1283 Pool Id: 8a85f981302cbaf201302d899adf05a9
1284 Quantity: 249237
1285 Service Level: None
1286 Service Type: None
1287 Multi-Entitlement: No
1288 Starts: 01/01/2021
1289 Ends: 01/01/2022
1290 Machine Type: physical
1291 The list command can also be used to show what products you currently
1294 have installed, as a way of tracking what products you have versus what
1295 subscriptions you have on the system.
1296 subscription-manager list --installed
1298 +-------------------------------------------+
1300 Installed Product Status
1301 +-------------------------------------------+
1302 ProductName: Red Hat Enterprise Linux Server
1304 Product ID: 69
1305 Version: 6.3
1306 Arch: x86_64
1307 Status: Subscribed
1308 Started: 07/26/2012
1309 Ends: 08/31/2015
1310 The list can be filtered to only include products or subscriptions that
1313 match the query string provided to --matches option.
1314 subscription-manager list --installed --matches="*Server*"
1316 +-------------------------------------------+
1318 Installed Product Status
1319 +-------------------------------------------+
1320 ProductName: Red Hat Enterprise Linux Server
1322 Product ID: 69
1323 Version: 6.3
1324 Arch: x86_64
1325 Status: Subscribed
1326 Started: 07/26/2012
1327 Ends: 08/31/2015
1328 Attaching a subscription requires the ID for the subscription pool (the
1331 --pool option). For example:
1332 subscription-manager attach
1334 --pool=ff8080812bc382e3012bc3845da100d2
1335 As with the register command, the system can be auto-attached to the
1337 best-fitting subscriptions. This is the default action and is equiva‐
1338 lent to using the --auto option:
1339 subscription-manager attach
1341 Auto-attach also supports an option to set a preferred service level
1345 with the selected subscriptions, the --servicelevel option. In this
1346 case, the --servicelevel option sets a preference that helps the auto-
1347 attach process select appropriate subscriptions. For example, if the
1348 preferred service level for a production server is premium, and there
1349 are three matching subscriptions with different service levels (none,
1350 standard, and premium), the auto-attach process selects the subscrip‐
1351 tion which offers a premium subscription.
1352 subscription-manager attach --servicelevel=premium
1354 Some subscriptions define a count based on attributes of the system it‐
1357 self, like the number of sockets or the number of virtual guests on a
1358 host. You can combine multiple subscriptions together to cover the
1359 count. For example, if there is a four socket server, you can use two
1360 subscriptions for "RHEL Server for Two Sockets" to cover the socket
1361 count. To specify the number of subscriptions to use, use the --quan‐
1362 tity option. For example:
1363 subscription-manager attach
1365 --pool=ff8080812bc382e3012bc3845da100d2
1366 --quantity=2
1367 Removing subscription from a system releases the subscription back into
1370 the pool. The system remains registered with the subscription manage‐
1371 ment service. Each product has an identifying X.509 certificate in‐
1372 stalled with it. To remove a subscription for a specific product, spec‐
1373 ify the serial number (or numbers, in multiple --serial options) of the
1374 certificate:
1375 subscription-manager remove --serial=1128750306742160
1377 Giving the remove command with the --all option removes every subscrip‐
1380 tion the system has used.
1381 REDEEMING EXISTING SUBSCRIPTIONS
1385 Sometimes, a system may come preconfigured with products and subscrip‐
1386 tions. Rather than attaching a pool and claiming a subscription, this
1387 system simply needs to redeem its existing subscriptions.
1388 After registration, subscriptions on preconfigured systems can be
1391 claimed using the redeem command, which essentially auto-attaches the
1392 system to its preexisting subscriptions.
1393 subscription-manager redeem --email=admin@example.com --org="IT Dept"
1395 VIEWING LOCAL SUBSCRIPTION & CONTENT PROVIDER INFORMATION
1398 Red Hat has a hosted environment, through the Customer Portal, that
1399 provides centralized access to subscription management and content
1400 repositories. However, organizations can use other tools -- like Sub‐
1401 scription Manager -- for content hosting and subscription management.
1402 With a local content provider, the organization, environments, reposi‐
1403 tories, and other structural configuration is performed in the content
1404 provider. Red Hat Subscription Manager can be used to display this in‐
1405 formation, using the environments, orgs, and repos commands.
1406 subscription-manager repos --list
1408 subscription-manager environments --username=jsmith
1410 --password=secret --org=prod
1411 or
1413 subscription-manager environments --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo --org=prod
1415 subscription-manager orgs --username=jsmith
1418 --password=secret
1419 or
1421 subscription-manager orgs --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo
1423 CHANGING SUBSCRIPTION MANAGER CONFIGURATION
1426 The Subscription Manager CLI and GUI both use the /etc/rhsm/rhsm.conf
1427 file for configuration, including what content and subscription manage‐
1428 ment services to use and management settings like auto-attaching. This
1429 configuration file can be edited directly, or it can be edited using
1430 the config command. Parameters and values are passed as arguments with
1431 the config command in the format --section.parameter=value , where sec‐
1432 tion is the configuration section in the file: server, rhsm, rhsmcertd
1433 or logging.
1434 For example, to change the hostname of the subscription management ser‐
1437 vice host:
1438 subscription-manager config --server.hostname=myserver.example.com
1440 The entries in the logging section are somewhat special. The keys in
1443 this section are a name of a logger. The values are the logging level.
1444 Valid levels are one of: DEBUG , INFO , WARNING , ERROR , or CRITICAL
1446 Valid logger names are the full module path of any Subscription Manager
1448 module. For example: subscription_manager or subscription_manager.man‐
1449 agercli
1450 There are three main top-level loggers: subscription_manager, rhsm, and
1453 rhsm-app. All logger names begin with one of the above.
1454 To set the default log level for all loggers (that are not otherwise
1457 set in the logging section), edit the default_log_level key in
1458 /etc/rhsm/rhsm.conf
1459 UPDATING FACTS
1463 The information about a system, such as its hardware and CPU, its oper‐
1464 ating system versions, and memory, are collected by Subscription Man‐
1465 ager in a list of facts. Subscription Manager uses these facts to de‐
1466 termine what purchased subscriptions are compatible with the system.
1467 Whenever these facts change (such as installing an additional CPU), the
1468 facts can be updated immediately using the facts command.
1469 subscription-manager facts --update
1471 The collected facts can also be overridden by creating a JSON file in
1473 the /etc/rhsm/facts/ directory. These have simple formats that define a
1474 fact and value:
1475 {"fact1": "value1","fact2": "value2"}
1477 Any fact override file must have a .facts extension.
1480 When these fact files are added, running the facts command will update
1483 the collected facts with the new, manual facts or values.
1484 SUBSCRIPTIONS AND KICKSTART
1487 The subscription-manager tool can be run as a post-install script as
1488 part of the kickstart installation process. This allows subscription
1489 management (registering and applying subscriptions) to be automated
1490 along with installation. For example:
1491 %post --log=/root/ks-post.log
1493 /usr/sbin/subscription-manager register --username admin --password secret --org 'east colo' --auto-attach --servicelevel=premium --force
1494
1497 The subscription-manager tool uses outgoing HTTPS requests. In the de‐
1498 fault configuration it will use HTTPS on port 443 to the subscription
1499 servers subscription.rhsm.redhat.com and to the content delivery ser‐
1500 vice cdn.redhat.com.
1501 For information about the network addresses that subscription-manager
1503 and the subscription-manager yum plugin use see https://access.red‐
1504 hat.com/site/solutions/59586
1505
1508 subscription-manager can be configured to use a proxy in several ways:
1509 * via standard HTTP_PROXY , HTTPS_PROXY , NO_PROXY environment
1511 variables (environment-level settings)
1512 * via options in /etc/rhsm/rhsm.conf (application-level set‐
1514 tings)
1515 * via command-line arguments (command-level overrides)
1517 Although subscription-manager respects environment variables for proxy
1520 configuration, this should be avoided in favor of the configuration
1521 file, because the daemons (ex. rhsmcertd ) do not provide ways to mod‐
1522 ify their environments.
1523 Each option of the proxy configuration (hostname, port, host/domain
1525 pattern blacklist, username, password) is read independently, with
1526 precedence being command-line over configuration over environment, and
1527 then the resulting set of options is used to configure the proxy con‐
1528 figuration.
1529 For example, if the HTTP_PROXY environment variable is set and no_proxy
1531 is set in /etc/rhsm/rhsm.conf then both are present in the effective
1532 proxy configuration.
1533 If two equivalent options are set in different places, then the prece‐
1535 dence determines which value is effective.
1536 For example, the NO_PROXY environment variable is set and the no_proxy
1538 configuration file option is set, then the value from the configuration
1539 file is the effective value.
1540
1543 * /etc/pki/consumer/*.pem
1544 * /etc/pki/entitlement/<serial>.pem
1546 * /etc/pki/product/*.pem
1548 * /etc/rhsm/rhsm.conf
1550 * /etc/rhsm/facts/*.facts
1552
1555 Deon Lackey, <dlackey@redhat.com>, and Pradeep Kilambi, <pkilambi@red‐
1556 hat.com>
1557 subscription-manager(8)