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. addons
105 8. role
108 9. service-level
111 10. usage
114 11. import
117 12. redeem
120 13. list
123 14. refresh
126 15. environments
129 16. repos
132 17. orgs
135 18. plugins
138 19. identity
141 20. facts
144 21. clean
147 22. config
150 23. version
153 24. status
156 25. deprecated commands: subscribe, unsubscribe, and activate
159 26. repo-override
162 COMMON OPTIONS
166 -h, --help
167 Prints the specific help information for the given command.
168 --proxy=PROXY
171 Uses an HTTP proxy. The PROXY name has the format hostname:port.
172 --proxyuser=PROXYUSERNAME
176 Gives the username to use to authenticate to the HTTP proxy.
177 --proxypass=PROXYPASSWORD
180 Gives the password to use to authenticate to the HTTP proxy.
181 --noproxy=NOPROXY
184 Specifies a list of domain suffixes which should bypass the HTTP
185 proxy.
186 REGISTER OPTIONS
189 The register command registers a new system to the subscription manage‐
190 ment service.
191 --username=USERNAME
194 Gives the username for the account which is registering the sys‐
195 tem; this user account is usually tied to the user account for
196 the content delivery system which supplies the content. Op‐
197 tional, for user-based authentication.
198 --password=PASSWORD
201 Gives the user account password.
202 --token=TOKEN
205 Token to use when authorizing against the server.
206 --serverurl=SERVER_HOSTNAME
209 Passes the name of the subscription service with which to regis‐
210 ter the system. The default value, if this is not given, is the
211 Customer Portal Subscription Management service, subscrip‐
212 tion.rhsm.redhat.com. If there is an on-premise subscription
213 service such as Subscription Asset Manager, this parameter can
214 be used to submit the hostname of the subscription service. For
215 Subscription Asset Manager, if the Subscription Manager tool is
216 configured with the Subscription Asset Manager RPM, then the de‐
217 fault value for the --serverurl parameter is for the on-premise
218 Subscription Asset Manager server.
219 --baseurl=https://CONTENT_SERVICE:PORT/PREFIX
223 Passes the name of the content delivery service to configure the
224 yum service to use to pull down packages. If there is an on-
225 premise subscription service such as Subscription Asset Manager
226 or CloudForms System Engine, this parameter can be used to sub‐
227 mit the URL of the content repository, in the form
228 https://server_name:port/prefix. PREFIX in particular depends
229 on the service type. For example, https://sam.exam‐
230 ple.com:8088/sam is the baseurl for a SAM service.
231 https://sat6.example.com/pulp/repos is the baseurl for a Satel‐
232 lite 6 service with the hostname sat6.example.com .
233 https://cdn.redhat.com is the baseurl for the Red Hat CDN.
234 --name=SYSTEM_NAME
238 Sets the name of the system to register. This defaults to the
239 hostname.
240 --consumerid=CONSUMERID
244 References an existing system inventory ID to resume using a
245 previous registration for this system. The ID is used as an in‐
246 ventory number for the system in the subscription management
247 service database. If the system's identity is lost or corrupted,
248 this option allows it to resume using its previous identity and
249 subscriptions.
250 --activationkey=KEYS
253 Gives a comma-separated list of product keys to use to redeem or
254 apply specific subscriptions to the system. This is used for
255 preconfigured systems which may already have products installed.
256 Activation keys are issued by an on-premise subscription manage‐
257 ment service, such as Subscription Asset Manager.
258 When the --activationkey option is used, it is not necessary to
260 use the --username and --password options, because the authenti‐
261 cation information is implicit in the activation key.
262 For example:
264 subscription-manager register --org="IT Dept" --activationkey=1234abcd
265 --auto-attach
268 Automatically attaches compatible subscriptions to this system.
269 --servicelevel=LEVEL
273 Sets the preferred service level to use with subscriptions added
274 to the system. Service levels are commonly premium, standard,
275 and none, though other levels may be available depending on the
276 product and the contract.
277 --force
280 Registers the system even if it is already registered. Normally,
281 any register operations will fail if the system is already reg‐
282 istered. With --force, the existing system entry is unregistered
283 first, all of its subscriptions are returned to the pool, and
284 then the system is registered as a new entry.
285 --org=ORG
288 Assigns the system to an organization. Infrastructures which are
289 managed on-site may be multi-tenant, meaning that there are mul‐
290 tiple organizations within one customer unit. A system may be
291 assigned manually to one of these organizations. When a system
292 is registered with the Customer Portal, this is not required.
293 When a system is registered with an on-premise application such
294 as Subscription Asset Manager, this argument is required, unless
295 there is only a single organization configured.
296 --environment=ENV
299 Registers the system to an environment within an organization.
300 --release=VERSION
303 Shortcut for "release --set=VERSION"
304 UNREGISTER OPTIONS
307 The unregister command removes a system's subscriptions and removes it
308 from the subscription management service.
309 This command has no options.
312 ATTACH OPTIONS
315 The attach command applies a specific subscription to the system.
316 --auto Automatically attaches the best-matched compatible subscription
319 or subscriptions to the system. This is the default unless
320 --pool or --file are used.
321 --pool=POOLID
324 Gives the ID for the subscriptions pool (collection of products)
325 to attach to the system. This overrides the default of --auto.
326 --file=FILE
329 Specifies a file from which to read whitespace-delimited pool
330 IDs. If FILE is "-", the pool IDs will be read from stdin. This
331 overrides the default of --auto.
332 --quantity=NUMBER
335 Attaches a specified number of subscriptions to the system. Sub‐
336 scriptions may have certain limits on them, like the number of
337 sockets on the system or the number of allowed virtual guests.
338 It is possible to attach multiple subscriptions (or stacking
339 subscriptions) to cover the number of sockets, guests, or other
340 characteristics. May not be used with an auto-attach.
341 --servicelevel=LEVEL
345 Sets the preferred service level to use with subscriptions auto‐
346 matically attached to the system. Service levels are commonly
347 premium, standard, and none, though other levels may be avail‐
348 able depending on the product and the contract. This option can‐
349 not be used when attaching specific pools via --pool or --file.
350 AUTO-ATTACH OPTIONS
353 The auto-attach command sets whether the ability to check, attach, and
354 update subscriptions occurs automatically on the system. Auto-attaching
355 subscriptions checks the currently-installed products, attached sub‐
356 scriptions, and any changes in available subscriptions every four hours
357 using the rhsmcertd daemon.
358 --enable
361 Enables the auto-attach option for the system. If there is any
362 change in the subscriptions for the system, any subscriptions
363 expire, or any new products are installed, then subscription-
364 manager detects the changes and automatically attaches the ap‐
365 propriate subscriptions so that the system remains covered.
366 --disable
369 Disables the auto-attach option for the system. If auto-attach
370 is disabled, then any changes in installed products or subscrip‐
371 tions for the system (including expired subscriptions) must be
372 addressed manually by the administrator.
373 --show Shows whether auto-attach is enabled on the systems.
376 REMOVE OPTIONS
379 The remove command removes a subscription from the system. (This does
380 not uninstall the associated products.)
381 --serial=SERIALNUMBER
384 Gives the serial number of the subscription certificate for the
385 specific product to remove from the system. Subscription cer‐
386 tificates attached to a system are in a certificate, in
387 /etc/pki/entitlement/<serial_number>.pem. To remove multiple
388 subscriptions, use the --serial option multiple times.
389 --pool=POOLID
392 Removes all subscription certificates for the specified pool id
393 from the system. To remove multiple sets of subscriptions, use
394 the --pool option multiple times.
395 --all Removes all of the subscriptions attached to a system.
398 RELEASE OPTIONS
402 The release command sets a sticky OS version to use when installing or
403 updating packages. This sets a preference for the minor version of the
404 OS, such as 6.2 or 6.3. This can prevent unplanned or unsupported oper‐
405 ating system version upgrades when an IT environment must maintain a
406 certified configuration.
407 --list Lists the available OS versions. If a release preference is not
410 set, then there is a message saying it is not set.
411 --set=RELEASE
414 Sets the minor (Y-stream) release version to use, such as 6.3.
415 --unset
418 Removes any previously set release version preference.
419 SYSPURPOSE OPTIONS
423 The syspurpose command displays the current configured syspurpose pref‐
424 erences for the system.
425 --show Shows the system's current set of syspurpose preference. This is
428 output in the form of a blob of json. Single-valued entries for
429 which there is no value will be included in the output with a
430 value of "". List entries which have no value will be included
431 in the output with a value of "[]" (less the quotes).
432 ADDONS OPTIONS
436 The addons command displays the current configured addons system pur‐
437 pose attribute preference for products installed on the system. For ex‐
438 ample, if the addons preference is ADDON1, then a subscription with a
439 ADDON1 addon is selected when auto-attaching subscriptions to the sys‐
440 tem.
441 --show Shows the system's current addons preference. If a addons is not
444 set, then there is a message saying it is not set.
445 --list Lists the available addons system purpose values.
448 --username=USERNAME
451 Gives the username for the account to use to connect to the or‐
452 ganization account [Use with --list when unregistered].
453 --password=PASSWORD
456 Gives the user account password [Use with --list when unregis‐
457 tered].
458 --token=TOKEN
461 Token to use when authorizing against the server [Use with
462 --list when unregistered].
463 --add=ADDON
466 Addon to add to the list of requested addons for this system
467 --remove=ADDON
470 Remove the addon from the list of requested addons.
471 --unset
474 Removes all addons from the list of requested addons.
475 ROLE OPTIONS
479 The role command displays the current configured role preference for
480 products installed on the system. For example, if the role preference
481 is "Red Hat Enterprise Linux Server", then a subscription with a "Red
482 Hat Enterprise Linux Server" role is selected when auto-attaching sub‐
483 scriptions to the system.
484 --show Shows the system's current role preference. If a role is not
487 set, then there is a message saying it is not set.
488 --list Lists the available role system purpose values.
491 --username=USERNAME
494 Gives the username for the account to use to connect to the or‐
495 ganization account [Use with --list when unregistered].
496 --password=PASSWORD
499 Gives the user account password [Use with --list when unregis‐
500 tered].
501 --token=TOKEN
504 Token to use when authorizing against the server [Use with
505 --list when unregistered].
506 --set=ROLE
509 Role to apply to this system
510 --unset
513 Removes any previously set role preference.
514 SERVICE-LEVEL OPTIONS
518 The service-level command displays the current configured service level
519 preference for products installed on the system. For example, if the
520 service-level preference is standard, then a subscription with a stan‐
521 dard service level is selected when auto-attaching subscriptions to the
522 system.
523 --serverurl=SERVER_URL
526 Server URL in the form of https://hostname:port/prefix
527 --insecure
530 Do not check the server SSL certificate against available cer‐
531 tificate authorities
532 --show Shows the system's current service-level preference. If a ser‐
535 vice level is not set, then there is a message saying it is not
536 set.
537 --list Lists the available service levels.
540 --username=USERNAME
543 Gives the username for the account to use to connect to the or‐
544 ganization account [Use with --list when unregistered].
545 --password=PASSWORD
548 Gives the user account password [Use with --list when unregis‐
549 tered].
550 --token=TOKEN
553 Token to use when authorizing against the server [Use with
554 --list when unregistered].
555 --set=SERVICE_LEVEL
558 Service level to apply to this system
559 --unset
562 Removes any previously set service-level preference.
563 USAGE OPTIONS
567 The usage command displays the current configured usage preference for
568 products installed on the system. For example, if the usage preference
569 is "Production", then a subscription with a "Production" usage is se‐
570 lected when auto-attaching subscriptions to the system.
571 --show Shows the system's current usage preference. If a usage is not
574 set, then there is a message saying it is not set.
575 --list Lists the available usage system purpose values.
578 --username=USERNAME
581 Gives the username for the account to use to connect to the or‐
582 ganization account [Use with --list when unregistered].
583 --password=PASSWORD
586 Gives the user account password [Use with --list when unregis‐
587 tered].
588 --token=TOKEN
591 Token to use when authorizing against the server [Use with
592 --list when unregistered].
593 --set=USAGE
596 Usage to apply to this system
597 --unset
600 Removes any previously set usage preference.
601 IMPORT OPTIONS
605 The import command imports and applies a subscription certificate for
606 the system which was generated externally, such as in the Customer Por‐
607 tal, and then copied over to the system. Importing can be necessary if
608 a system is preconfigured in the subscription management service or if
609 it is offline or unable to access the subscription management service
610 but it has the proper, relevant subscriptions attached to the system.
611 --certificate=CERTIFICATE_FILE
614 Points to a certificate PEM file which contains the subscription
615 certificate. This can be used multiple times to import multiple
616 subscription certificates.
617 REDEEM OPTIONS
620 The redeem command is used for systems that are purchased from third-
621 party vendors that include a subscription. The redemption process es‐
622 sentially auto-attaches the preselected subscription that the vendor
623 supplied to the system.
624 --email=EMAIL
627 Gives the email account to send the redemption notification mes‐
628 sage to.
629 --locale=LOCALE
632 Sets the locale to use for the message. If none is given, then
633 it defaults to the local system's locale.
634 LIST OPTIONS
638 The list command lists all of the subscriptions that are compatible
639 with a system. The options allow the list to be filtered by subscrip‐
640 tions that are used by the system or unused subscriptions that are
641 available to the system.
642 --afterdate=YYYY-MM-DD
645 Shows pools that are active on or after the given date. This is
646 only used with the --available option.
647 --all Lists all possible subscriptions that have been purchased, even
650 if they don't match the architecture of the system. This is used
651 with the --available option.
652 --available
655 Lists available subscriptions which are not yet attached to the
656 system.
657 --consumed
660 Lists all of the subscriptions currently attached to the system.
661 --installed
664 Lists products which are currently installed on the system which
665 may (or may not) have subscriptions associated with them, as
666 well as products with attached subscriptions which may (or may
667 not) be installed. (default)
668 --ondate=YYYY-MM-DD
671 Sets the date to use to search for active and available sub‐
672 scriptions. The default (if not explicitly passed) is today's
673 date; using a later date looks for subscriptions which will be
674 active then. This is only used with the --available option.
675 --no-overlap
678 Shows pools which provide products that are not already covered;
679 only used with --available option.
680 --match-installed
683 Shows only subscriptions matching products that are currently
684 installed; only used with --available option.
685 --matches=SEARCH
688 Limits the output of --installed, --available and --consumed to
689 only subscriptions or products which contain SEARCH in the sub‐
690 scription or product information, varying with the list re‐
691 quested and the server version.
692 SEARCH may contain the wildcards ? or * to match a single char‐
693 acter or zero or more characters, respectively. The wildcard
694 characters may be escaped with a backslash to represent a lit‐
695 eral question mark or asterisk. Likewise, to represent a back‐
696 slash, it must be escaped with another backslash.
697 --pool-only
700 Limits the output of --available and --consumed such that only
701 the pool IDs are displayed. No labels or errors will be printed
702 if this option is specified.
703 REFRESH OPTIONS
706 The refresh command pulls the latest subscription data from the server.
707 Normally, the system polls the subscription management service at a set
708 interval (4 hours by default) to check for any changes in the available
709 subscriptions. The refresh command checks with the subscription manage‐
710 ment service right then, outside the normal interval.
711 --force
714 Force regeneration of entitlement certificates on the server be‐
715 fore these certificates are pulled from the server.
716 ENVIRONMENTS OPTIONS
720 The environments command lists all of the environments that have been
721 configured for an organization. This command is only used for organiza‐
722 tions which have a locally-hosted subscription or content service of
723 some kind, like Subscription Asset Manager. The concept of environments
724 -- and therefore this command -- have no meaning for environments which
725 use the Customer Portal Subscription Management services.
726 --username=USERNAME
729 Gives the username for the account to use to connect to the or‐
730 ganization account.
731 --password=PASSWORD
734 Gives the user account password.
735 --token=TOKEN
738 Token to use when authorizing against the server.
739 --org=ORG
742 Identifies the organization for which to list the configured en‐
743 vironments.
744 REPOS OPTIONS
748 The repos command lists all of the repositories that are available to a
749 system. This command is only used for organizations which have a lo‐
750 cally-hosted content service of some kind, like Subscription Asset Man‐
751 ager. With Red Hat's hosted content service, there is only one central
752 repository.
753 --list Lists all of the repositories that are provided by the content
756 service used by the system.
757 --list-enabled
760 Lists all of the enabled repositories that are provided by the
761 content service used by the system.
762 --list-disabled
765 Lists all of the disabled repositories that are provided by the
766 content service used by the system.
767 --enable=REPO_ID
770 Enables the specified repository, which is made available by the
771 content sources identified in the system subscriptions. To en‐
772 able multiple repositories, use this argument multiple times.
773 Wild cards * and ? are supported.
774 --disable=REPO_ID
777 Disables the specified repository, which is made available by
778 the content sources identified in the system subscriptions. To
779 disable multiple repositories, use this argument multiple times.
780 Wild cards * and ? are supported.
781 ORGS OPTIONS
785 The orgs command lists all of the organizations which are available to
786 the specified user account. A multi-tenant infrastructure may have mul‐
787 tiple organizations within a single customer, and users may be re‐
788 stricted to access only a subset of the total number of organizations.
789 --username=USERNAME
792 Gives the username for the account to use to connect to the or‐
793 ganization account.
794 --password=PASSWORD
797 Gives the user account password.
798 --token=TOKEN
801 Token to use when authorizing against the server.
802 --serverurl=SERVER_HOSTNAME
805 Passes the name of the subscription service to use to list all
806 available organizations. The orgs command will list all organi‐
807 zations for the specified service for which the user account is
808 granted access. The default value, if this is not given, is the
809 Customer Portal Subscription Management service, https://sub‐
810 scription.rhsm.redhat.com:443. If there is an on-premise sub‐
811 scription service such as Subscription Asset Manager, this pa‐
812 rameter can be used to submit the hostname of the subscription
813 service, in the form [protocol://]servername[:port][/prefix].
814 For Subscription Asset Manager, if the Subscription Manager tool
815 is configured with the Subscription Asset Manager RPM, then the
816 default value for the --serverurl parameter is for the on-
817 premise Subscription Asset Manager server.
818 PLUGIN OPTIONS
822 The plugins command lists the available subscription-manager plugins.
823 --list List the available subscription-manager plugins.
826 --listslots
829 List the available plugin slots
830 --listhooks
833 List the available plugin slots and the hooks that handle them.
834 --verbose
837 Show additional info about the plugins, such as the plugin con‐
838 figuration values.
839 REPO-OVERRIDE OPTIONS
842 The repo-override command allows the user to manage custom content
843 repository settings
844 --repo The repository to modify (can be specified more than once)
847 --add=NAME:VALUE
850 Adds a named override with the provided value to repositories
851 specified with the --repo option
852 --remove=NAME
855 Removes a named override from the repositories specified with
856 the --repo option
857 --remove-all
860 Removes all overrides from repositories specified with the
861 --repo option
862 --list Lists all overrides from repositories specified with the --repo
865 option
866 IDENTITY OPTIONS
870 The identity command handles the UUID of a system, which identifies the
871 system to the subscription management service after registration. This
872 command can simply return the UUID or it can be used to restore the
873 registration of a previously-registered system to the subscription man‐
874 agement service.
875 --regenerate
878 Requests that the subscription management service issue a new
879 identity certificate for the system, using an existing UUID in
880 the original identity certificate. If this is used alone, then
881 the identity command also uses the original identity certificate
882 to bind to the subscription management service, using certifi‐
883 cate-based authentication.
884 --username=USERNAME
887 Gives the username for the account which is registering the sys‐
888 tem; this user account is usually tied to the user account for
889 the content delivery system which supplies the content. Op‐
890 tional, for user-based authentication.
891 --password=PASSWORD
894 Gives the user account password. Optional, for user-based au‐
895 thentication.
896 --token=TOKEN
899 Token to use when authorizing against the server.
900 --force
903 Regenerates the identity certificate for the system using user‐
904 name/password or token authentication. This is used with the
905 --regenerate option. --regenerate alone will use an existing
906 identity certificate to authenticate to the subscription manage‐
907 ment service. If the certificate is missing or corrupted or in
908 other circumstances, then it may be better to use user authenti‐
909 cation rather than certificate-based authentication. In that
910 case, the --force option requires the username or password or
911 token to be given either as an argument or in response to a
912 prompt.
913 FACTS OPTIONS
917 The facts command lists the system information, like the release ver‐
918 sion, number of CPUs, and other architecture information.
919 --list Lists the system information. These are simple attribute: value
922 pairs that reflect much of the information in the /etc/sysconfig
923 directory
924 cpu.architecture: x86_64
925 cpu.core(s)_per_socket: 1
926 cpu.cpu(s): 2
927 cpu.cpu_family: 6
928 cpu.cpu_mhz: 1861.776
929 cpu.cpu_op-mode(s): 64-bit
930 cpu.cpu_socket(s): 2
931 cpu.hypervisor_vendor: KVM
932 cpu.model: 2
933 cpu.numa_node(s): 1
934 cpu.numa_node0_cpu(s): 0,1
935 cpu.stepping: 3
936 cpu.thread(s)_per_core: 1
937 cpu.vendor_id: GenuineIntel
938 cpu.virtualization_type: full
939 distribution.id: Santiago
940 distribution.name: Red Hat Enterprise Linux Workstation
941 distribution.version: 6.1
942 ----
943 --update
947 Updates the system information. This is particularly important
948 whenever there is a hardware change (such as adding a CPU) or a
949 system upgrade because these changes can affect the subscrip‐
950 tions that are compatible with the system.
951 CLEAN OPTIONS
954 The clean command removes all of the subscription and identity data
955 from the local system without affecting the system information in the
956 subscription management service. This means that any of the subscrip‐
957 tions applied to the system are not available for other systems to use.
958 The clean command is useful in cases where the local subscription in‐
959 formation is corrupted or lost somehow, and the system will be re-reg‐
960 istered using the register --consumerid=EXISTING_ID command.
961 This command has no options.
964 CONFIG OPTIONS
967 The config command changes the rhsm.conf configuration file used by
968 Subscription Manager. Almost all of the connection information used by
969 Subscription Manager to access the subscription management service,
970 content server, and any proxies is set in the configuration file, as
971 well as general configuration parameters like the frequency Subscrip‐
972 tion Manager checks for subscriptions updates. There are major divi‐
973 sions in the rhsm.conf file, such as [server] which is used to config‐
974 ure the subscription management service. When changing the Subscription
975 Manager configuration, the settings are identified with the format sec‐
976 tion.name and then the new value. For example:
977 server.hostname=newsubscription.example.com
979 --list Prints the current configuration for Subscription Manager.
982 --remove=section.name
985 Deletes the current value for the parameter without supplying a
986 new parameter. A blank value tells Subscription Manager to use
987 service default values for that parameter. If there are no de‐
988 faults, then the feature is ignored.
989 --section.name=VALUE
992 Sets a parameter to a new, specified value. This is commonly
993 used for connection settings:
994 * server.hostname (subscription management service)
996 * server.proxy
998 * server.proxy_port
1000 * server.proxy_user
1002 * server.proxy_password
1004 * rhsm.baseurl (content server)
1006 * rhsm.certFrequency
1008 VERSION OPTIONS
1011 The version command displays information about the current Subscription
1012 Manager package, the subscription service the system is registered to
1013 (if it is currently registered), and the subscription management server
1014 that the system is configured to use. For example:
1015 [root@server ~]# subscription-manager version
1017 server type: Red Hat Subscription Management
1018 subscription management server: 0.9.18-1
1019 subscription management rules: 5.9
1020 subscription-manager: 1.12.1-1.git.28.5cd97a5.fc20
1021 python-rhsm: 1.11.4-1.git.1.2f38ded.fc20
1022 This command has no options.
1025 STATUS OPTIONS
1029 The status command shows the current status of the products and at‐
1030 tached subscriptions for the system. If some products are not fully
1031 covered or subscriptions have expired, then the status command shows
1032 why subscriptions are not current and returns an error code.
1033 [root@server ~]# subscription-manager status
1035 +-------------------------------------------+
1036 System Status Details
1037 +-------------------------------------------+
1038 Overall Status: Current
1039 --ondate=DATE
1043 Shows the system status for a specific date in the future. The
1044 format of the date is YYYY-MM-DD.
1045 [root@server ~]# subscription-manager status --ondate=2014-01-01
1047 +-------------------------------------------+
1048 System Status Details
1049 +-------------------------------------------+
1050 Overall Status: Insufficient
1051 DEPRECATED COMMANDS
1054 As the structures of subscription configuration have changed, some of
1055 the original management commands have become obsolete. These commands
1056 have been replaced with updated commands.
1057 subscribe
1060 This has been replaced with attach. A similar registration op‐
1061 tion, --subscribe, has also be replaced with --auto-attach.
1062 unsubscribe
1065 This has been replaced with remove.
1066 activate
1069 This has been replaced with redeem.
1070
1073 subscription-manager has two major tasks:
1074 1. Handling the registration for a given system to a subscrip‐
1077 tion management service
1078 2. Handling the product subscriptions for installed products on
1081 a system
1082 subscription-manager makes it easier for network administrators to
1085 maintain parity between software subscriptions and updates and their
1086 installed products by tracking and managing what subscriptions are at‐
1087 tached to a system and when those subscriptions expire or are exceeded.
1088 REGISTERING AND UNREGISTERING MACHINES
1092 A system is either registered to a subscription management service --
1093 which makes all of the subscriptions available to the system -- or it
1094 is not registered. Unregistered systems necessarily lack valid software
1095 subscriptions because there is no way to record that the subscriptions
1096 have been used nor any way to renew them.
1097 The default subscription management service in the Subscription Manager
1100 configuration is the Customer Portal Subscription Management service.
1101 The configuration file can be edited before the system is registered to
1102 point to an on-premise subscription management service like Subscrip‐
1103 tion Asset Manager.
1104 Systems are usually registered to a subscription management service as
1107 part of their initial configuration, such as the firstboot or kickstart
1108 process. However, systems can be registered manually after they are
1109 configured, can be removed from a content service, or re-registered.
1110 If a system has never been registered (not even during firstboot), then
1113 the register command will register the system with whatever subscrip‐
1114 tion management service is configured in the /etc/rhsm/rhsm.conf file.
1115 This command requires, at a minimum, the username and password or token
1116 for an account to connect to the subscription management service. If
1117 the credentials aren't passed with the command, then subscription-man‐
1118 ager prompts for the username and password interactively.
1119 When there is a single organization or when using the Customer Portal
1122 Subscription Management service, all that is required is the user‐
1123 name/password set or the token is used. For example:
1124 subscription-manager register --username=admin --password=secret or subscription-manager register --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo
1126 With on-premise subscription services, such as Subscription Asset Man‐
1129 ager, the infrastructure is more complex. The local administrator can
1130 define independent groups called organizations which represent physical
1131 or organizational divisions (--org). Those organizations can be subdi‐
1132 vided into environments (--environment). Optionally, the information
1133 about what subscription service (--serverurl) and content delivery net‐
1134 work (--baseurl) to use for the system registration can also be passed
1135 (which overrides the Red Hat Subscription Manager settings). The server
1136 and content URLs are usually configured in the Subscription Manager
1137 configuration before registering a system.
1138 subscription-manager register --username=admin --password=secret
1140 --org="IT Dept" --environment="local dev" --serverurl=local-cloudforms.example.com --baseurl=https://local-cloudforms.example.com:8088/cfFe
1141 If a system is in a multi-tenant environment and the organization is
1145 not provided with the registration request, registration fails with a
1146 remote server error. In the rhsm.log, there will be errors about being
1147 unable to load the owners interface.
1148 If a system is registered and then somehow its subscription information
1152 is lost -- a drive crashes or the certificates are deleted or corrupted
1153 -- the system can be re-registered, with all of its subscriptions re‐
1154 stored, by registering with the existing ID.
1155 subscription-manager register --username=admin
1157 --password=secret --consumerid=1234abcd
1158 A system uses an SSL client certificate (its identity certificate) to
1161 authenticate to the subscriptions system to check for updates or
1162 changes to subscriptions. If the identity certificate is lost or cor‐
1163 rupted, it can be regenerated using the identity command.
1164 subscription-manager identity --regenerate
1166 Using the --force option will prompt for the username and password for
1169 the account, if one isn't given, and then return the new inventory ID
1170 and the hostname of the registered system.
1171 subscription-manager identity --force
1173 Username: jsmith
1174 Password:
1175 eff9a4c9-3579-49e5-a52f-83f2db29ab52 server.example.com
1176 A system is unregistered and removed from the subscription management
1180 service simply by running the unregister command. Unregistering a sys‐
1181 tem and removing its attached subscriptions can free up subscriptions
1182 when a system is taken offline or moved to a different department.
1183 subscription-manager unregister
1185 An option with registration, --auto-attach, will automatically attach
1188 the subscriptions pool which best matches the system architecture and
1189 configuration to the newly-registered system. This option attaches sub‐
1190 scriptions as part of the registration process, rather than separately
1191 managing subscriptions.
1192 subscription-manager register --username=admin --password=secret
1194 --auto-attach
1195 Auto-attach also supports an option to set a preferred service level
1198 with the selected subscriptions, the --servicelevel option. In this
1199 case, the --servicelevel option sets a preference that helps the auto-
1200 attach process select appropriate subscriptions. For example, if the
1201 preferred service level for a production server is premium, and there
1202 are three matching subscriptions with different service levels (none,
1203 standard, and premium), the auto-attach process selects the subscrip‐
1204 tion which offers a premium service level.
1205 subscription-manager register --username=admin --password=secret
1207 --auto-attach --servicelevel=premium
1208 LISTING, ATTACHING, AND REMOVING SUBSCRIPTIONS FOR PRODUCTS
1211 A subscription is essentially the right to install, use, and receive
1212 updates for a Red Hat product. (Sometimes multiple individual software
1213 products are bundled together into a single subscription.) When a sys‐
1214 tem is registered, the subscription management service is aware of the
1215 system and has a list of all of the possible product subscriptions that
1216 the system can install and use. A subscription is applied to a system
1217 when the system is attached to the subscription pool that makes that
1218 product available. A system releases or removes that subscription
1219 (meaning, it removes that subscription so that another system can use
1220 that subscription count).
1221 list command shows you what subscriptions are available specifically to
1224 the system (meaning subscriptions which are active, have available
1225 quantities, and match the hardware and architecture) or all subscrip‐
1226 tions for the organization. Using the --ondate option shows subscrip‐
1227 tions that are or will be active at a specific time (otherwise, it
1228 shows subscriptions which are active today).
1229 subscription-manager list --available --ondate=2012-01-31
1231 +-------------------------------------------+
1232 Available Subscriptions
1233 +-------------------------------------------+
1234 Subscription Name: Red Hat Enterprise Linux
1235 SKU: SYS0395
1236 Pool Id: 8a85f981302cbaf201302d899adf05a9
1237 Quantity: 249237
1238 Service Level: None
1239 Service Type: None
1240 Multi-Entitlement: No
1241 Starts: 01/01/2021
1242 Ends: 01/01/2022
1243 Machine Type: physical
1244 The list command can also be used to show what products you currently
1247 have installed, as a way of tracking what products you have versus what
1248 subscriptions you have on the system.
1249 subscription-manager list --installed
1251 +-------------------------------------------+
1253 Installed Product Status
1254 +-------------------------------------------+
1255 ProductName: Red Hat Enterprise Linux Server
1257 Product ID: 69
1258 Version: 6.3
1259 Arch: x86_64
1260 Status: Subscribed
1261 Started: 07/26/2012
1262 Ends: 08/31/2015
1263 The list can be filtered to only include products or subscriptions that
1266 match the query string provided to --matches option.
1267 subscription-manager list --installed --matches="*Server*"
1269 +-------------------------------------------+
1271 Installed Product Status
1272 +-------------------------------------------+
1273 ProductName: Red Hat Enterprise Linux Server
1275 Product ID: 69
1276 Version: 6.3
1277 Arch: x86_64
1278 Status: Subscribed
1279 Started: 07/26/2012
1280 Ends: 08/31/2015
1281 Attaching a subscription requires the ID for the subscription pool (the
1284 --pool option). For example:
1285 subscription-manager attach
1287 --pool=ff8080812bc382e3012bc3845da100d2
1288 As with the register command, the system can be auto-attached to the
1290 best-fitting subscriptions. This is the default action and is equiva‐
1291 lent to using the --auto option:
1292 subscription-manager attach
1294 Auto-attach also supports an option to set a preferred service level
1298 with the selected subscriptions, the --servicelevel option. In this
1299 case, the --servicelevel option sets a preference that helps the auto-
1300 attach process select appropriate subscriptions. For example, if the
1301 preferred service level for a production server is premium, and there
1302 are three matching subscriptions with different service levels (none,
1303 standard, and premium), the auto-attach process selects the subscrip‐
1304 tion which offers a premium subscription.
1305 subscription-manager attach --servicelevel=premium
1307 Some subscriptions define a count based on attributes of the system it‐
1310 self, like the number of sockets or the number of virtual guests on a
1311 host. You can combine multiple subscriptions together to cover the
1312 count. For example, if there is a four socket server, you can use two
1313 subscriptions for "RHEL Server for Two Sockets" to cover the socket
1314 count. To specify the number of subscriptions to use, use the --quan‐
1315 tity option. For example:
1316 subscription-manager attach
1318 --pool=ff8080812bc382e3012bc3845da100d2
1319 --quantity=2
1320 Removing subscription from a system releases the subscription back into
1323 the pool. The system remains registered with the subscription manage‐
1324 ment service. Each product has an identifying X.509 certificate in‐
1325 stalled with it. To remove a subscription for a specific product, spec‐
1326 ify the serial number (or numbers, in multiple --serial options) of the
1327 certificate:
1328 subscription-manager remove --serial=1128750306742160
1330 Giving the remove command with the --all option removes every subscrip‐
1333 tion the system has used.
1334 REDEEMING EXISTING SUBSCRIPTIONS
1338 Sometimes, a system may come preconfigured with products and subscrip‐
1339 tions. Rather than attaching a pool and claiming a subscription, this
1340 system simply needs to redeem its existing subscriptions.
1341 After registration, subscriptions on preconfigured systems can be
1344 claimed using the redeem command, which essentially auto-attaches the
1345 system to its preexisting subscriptions.
1346 subscription-manager redeem --email=admin@example.com --org="IT Dept"
1348 VIEWING LOCAL SUBSCRIPTION & CONTENT PROVIDER INFORMATION
1351 Red Hat has a hosted environment, through the Customer Portal, that
1352 provides centralized access to subscription management and content
1353 repositories. However, organizations can use other tools -- like Sub‐
1354 scription Manager -- for content hosting and subscription management.
1355 With a local content provider, the organization, environments, reposi‐
1356 tories, and other structural configuration is performed in the content
1357 provider. Red Hat Subscription Manager can be used to display this in‐
1358 formation, using the environments, orgs, and repos commands.
1359 subscription-manager repos --list
1361 subscription-manager environments --username=jsmith
1363 --password=secret --org=prod
1364 or
1366 subscription-manager environments --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo --org=prod
1368 subscription-manager orgs --username=jsmith
1371 --password=secret
1372 or
1374 subscription-manager orgs --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo
1376 CHANGING SUBSCRIPTION MANAGER CONFIGURATION
1379 The Subscription Manager CLI and GUI both use the /etc/rhsm/rhsm.conf
1380 file for configuration, including what content and subscription manage‐
1381 ment services to use and management settings like auto-attaching. This
1382 configuration file can be edited directly, or it can be edited using
1383 the config command. Parameters and values are passed as arguments with
1384 the config command in the format --section.parameter=value , where sec‐
1385 tion is the configuration section in the file: server, rhsm, rhsmcertd
1386 or logging.
1387 For example, to change the hostname of the subscription management ser‐
1390 vice host:
1391 subscription-manager config --server.hostname=myserver.example.com
1393 The entries in the logging section are somewhat special. The keys in
1396 this section are a name of a logger. The values are the logging level.
1397 Valid levels are one of: DEBUG , INFO , WARNING , ERROR , or CRITICAL
1399 Valid logger names are the full module path of any Subscription Manager
1401 module. For example: subscription_manager or subscription_manager.man‐
1402 agercli
1403 There are three main top-level loggers: subscription_manager, rhsm, and
1406 rhsm-app. All logger names begin with one of the above.
1407 To set the default log level for all loggers (that are not otherwise
1410 set in the logging section), edit the default_log_level key in
1411 /etc/rhsm/rhsm.conf
1412 UPDATING FACTS
1416 The information about a system, such as its hardware and CPU, its oper‐
1417 ating system versions, and memory, are collected by Subscription Man‐
1418 ager in a list of facts. Subscription Manager uses these facts to de‐
1419 termine what purchased subscriptions are compatible with the system.
1420 Whenever these facts change (such as installing an additional CPU), the
1421 facts can be updated immediately using the facts command.
1422 subscription-manager facts --update
1424 The collected facts can also be overridden by creating a JSON file in
1426 the /etc/rhsm/facts/ directory. These have simple formats that define a
1427 fact and value:
1428 {"fact1": "value1","fact2": "value2"}
1430 Any fact override file must have a .facts extension.
1433 When these fact files are added, running the facts command will update
1436 the collected facts with the new, manual facts or values.
1437 SUBSCRIPTIONS AND KICKSTART
1440 The subscription-manager tool can be run as a post-install script as
1441 part of the kickstart installation process. This allows subscription
1442 management (registering and applying subscriptions) to be automated
1443 along with installation. For example:
1444 %post --log=/root/ks-post.log
1446 /usr/sbin/subscription-manager register --username admin --password secret --org 'east colo' --auto-attach --servicelevel=premium --force
1447
1450 The subscription-manager tool uses outgoing HTTPS requests. In the de‐
1451 fault configuration it will use HTTPS on port 443 to the subscription
1452 servers subscription.rhsm.redhat.com and to the content delivery ser‐
1453 vice cdn.redhat.com.
1454 For information about the network addresses that subscription-manager
1456 and the subscription-manager yum plugin use see https://access.red‐
1457 hat.com/site/solutions/59586
1458
1461 subscription-manager can be configured to use a proxy in several ways:
1462 * via standard HTTP_PROXY , HTTPS_PROXY , NO_PROXY environment
1464 variables (environment-level settings)
1465 * via options in /etc/rhsm/rhsm.conf (application-level set‐
1467 tings)
1468 * via command-line arguments (command-level overrides)
1470 Although subscription-manager respects environment variables for proxy
1473 configuration, this should be avoided in favor of the configuration
1474 file, because the daemons (ex. rhsmcertd ) do not provide ways to mod‐
1475 ify their environments.
1476 Each option of the proxy configuration (hostname, port, host/domain
1478 pattern blacklist, username, password) is read independently, with
1479 precedence being command-line over configuration over environment, and
1480 then the resulting set of options is used to configure the proxy con‐
1481 figuration.
1482 For example, if the HTTP_PROXY environment variable is set and no_proxy
1484 is set in /etc/rhsm/rhsm.conf then both are present in the effective
1485 proxy configuration.
1486 If two equivalent options are set in different places, then the prece‐
1488 dence determines which value is effective.
1489 For example, the NO_PROXY environment variable is set and the no_proxy
1491 configuration file option is set, then the value from the configuration
1492 file is the effective value.
1493
1496 * /etc/pki/consumer/*.pem
1497 * /etc/pki/entitlement/<serial>.pem
1499 * /etc/pki/product/*.pem
1501 * /etc/rhsm/rhsm.conf
1503 * /etc/rhsm/facts/*.facts
1505
1508 Deon Lackey, <dlackey@redhat.com>, and Pradeep Kilambi, <pkilambi@red‐
1509 hat.com>
1510 subscription-manager(8)