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
24 allowed 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.
197 Optional, 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
217 default value for the --serverurl parameter is for the on-
218 premise 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
246 inventory 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 --no-insights
307 Stop insights from automatically registering using the subscrip‐
308 tion-manager identity.
309 UNREGISTER OPTIONS
312 The unregister command removes a system's subscriptions and removes it
313 from the subscription management service.
314 This command has no options.
317 ATTACH OPTIONS
320 The attach command applies a specific subscription to the system.
321 --auto Automatically attaches the best-matched compatible subscription
324 or subscriptions to the system. This is the default unless
325 --pool or --file are used.
326 --pool=POOLID
329 Gives the ID for the subscriptions pool (collection of products)
330 to attach to the system. This overrides the default of --auto.
331 --file=FILE
334 Specifies a file from which to read whitespace-delimited pool
335 IDs. If FILE is "-", the pool IDs will be read from stdin. This
336 overrides the default of --auto.
337 --quantity=NUMBER
340 Attaches a specified number of subscriptions to the system. Sub‐
341 scriptions may have certain limits on them, like the number of
342 sockets on the system or the number of allowed virtual guests.
343 It is possible to attach multiple subscriptions (or stacking
344 subscriptions) to cover the number of sockets, guests, or other
345 characteristics. May not be used with an auto-attach.
346 --servicelevel=LEVEL
350 Sets the preferred service level to use with subscriptions auto‐
351 matically attached to the system. Service levels are commonly
352 premium, standard, and none, though other levels may be avail‐
353 able depending on the product and the contract. This option can‐
354 not be used when attaching specific pools via --pool or --file.
355 AUTO-ATTACH OPTIONS
358 The auto-attach command sets whether the ability to check, attach, and
359 update subscriptions occurs automatically on the system. Auto-attaching
360 subscriptions checks the currently-installed products, attached sub‐
361 scriptions, and any changes in available subscriptions every four hours
362 using the rhsmcertd daemon.
363 --enable
366 Enables the auto-attach option for the system. If there is any
367 change in the subscriptions for the system, any subscriptions
368 expire, or any new products are installed, then subscription-
369 manager detects the changes and automatically attaches the
370 appropriate subscriptions so that the system remains covered.
371 --disable
374 Disables the auto-attach option for the system. If auto-attach
375 is disabled, then any changes in installed products or subscrip‐
376 tions for the system (including expired subscriptions) must be
377 addressed manually by the administrator.
378 --show Shows whether auto-attach is enabled on the systems.
381 REMOVE OPTIONS
384 The remove command removes a subscription from the system. (This does
385 not uninstall the associated products.)
386 --serial=SERIALNUMBER
389 Gives the serial number of the subscription certificate for the
390 specific product to remove from the system. Subscription cer‐
391 tificates attached to a system are in a certificate, in
392 /etc/pki/entitlement/<serial_number>.pem. To remove multiple
393 subscriptions, use the --serial option multiple times.
394 --pool=POOLID
397 Removes all subscription certificates for the specified pool id
398 from the system. To remove multiple sets of subscriptions, use
399 the --pool option multiple times.
400 --all Removes all of the subscriptions attached to a system.
403 RELEASE OPTIONS
407 The release command sets a sticky OS version to use when installing or
408 updating packages. This sets a preference for the minor version of the
409 OS, such as 6.2 or 6.3. This can prevent unplanned or unsupported oper‐
410 ating system version upgrades when an IT environment must maintain a
411 certified configuration.
412 --list Lists the available OS versions. If a release preference is not
415 set, then there is a message saying it is not set.
416 --set=RELEASE
419 Sets the minor (Y-stream) release version to use, such as 6.3.
420 --unset
423 Removes any previously set release version preference.
424 ADDONS OPTIONS
428 The addons command displays the current configured addons system pur‐
429 pose attribute preference for products installed on the system. For
430 example, if the addons preference is ADDON1, then a subscription with a
431 ADDON1 addon is selected when auto-attaching subscriptions to the sys‐
432 tem.
433 --show Shows the system's current addons preference. If a addons is not
436 set, then there is a message saying it is not set.
437 --list Lists the available addons system purpose values.
440 --username=USERNAME
443 Gives the username for the account to use to connect to the
444 organization account [Use with --list when unregistered].
445 --password=PASSWORD
448 Gives the user account password [Use with --list when unregis‐
449 tered].
450 --token=TOKEN
453 Token to use when authorizing against the server [Use with
454 --list when unregistered].
455 --add=ADDON
458 Addon to add to the list of requested addons for this system
459 --remove=ADDON
462 Remove the addon from the list of requested addons.
463 --unset
466 Removes all addons from the list of requested addons.
467 ROLE OPTIONS
471 The role command displays the current configured role preference for
472 products installed on the system. For example, if the role preference
473 is "Red Hat Enterprise Linux Server", then a subscription with a "Red
474 Hat Enterprise Linux Server" role is selected when auto-attaching sub‐
475 scriptions to the system.
476 --show Shows the system's current role preference. If a role is not
479 set, then there is a message saying it is not set.
480 --list Lists the available role system purpose values.
483 --username=USERNAME
486 Gives the username for the account to use to connect to the
487 organization account [Use with --list when unregistered].
488 --password=PASSWORD
491 Gives the user account password [Use with --list when unregis‐
492 tered].
493 --token=TOKEN
496 Token to use when authorizing against the server [Use with
497 --list when unregistered].
498 --set=ROLE
501 Role to apply to this system
502 --unset
505 Removes any previously set role preference.
506 SERVICE-LEVEL OPTIONS
510 The service-level command displays the current configured service level
511 preference for products installed on the system. For example, if the
512 service-level preference is standard, then a subscription with a stan‐
513 dard service level is selected when auto-attaching subscriptions to the
514 system.
515 --serverurl=SERVER_URL
518 Server URL in the form of https://hostname:port/prefix
519 --insecure
522 Do not check the server SSL certificate against available cer‐
523 tificate authorities
524 --show Shows the system's current service-level preference. If a ser‐
527 vice level is not set, then there is a message saying it is not
528 set.
529 --list Lists the available service levels.
532 --username=USERNAME
535 Gives the username for the account to use to connect to the
536 organization account [Use with --list when unregistered].
537 --password=PASSWORD
540 Gives the user account password [Use with --list when unregis‐
541 tered].
542 --token=TOKEN
545 Token to use when authorizing against the server [Use with
546 --list when unregistered].
547 --set=SERVICE_LEVEL
550 Service level to apply to this system
551 --unset
554 Removes any previously set service-level preference.
555 USAGE OPTIONS
559 The usage command displays the current configured usage preference for
560 products installed on the system. For example, if the usage preference
561 is "Production", then a subscription with a "Production" usage is
562 selected when auto-attaching subscriptions to the system.
563 --show Shows the system's current usage preference. If a usage is not
566 set, then there is a message saying it is not set.
567 --list Lists the available usage system purpose values.
570 --username=USERNAME
573 Gives the username for the account to use to connect to the
574 organization account [Use with --list when unregistered].
575 --password=PASSWORD
578 Gives the user account password [Use with --list when unregis‐
579 tered].
580 --token=TOKEN
583 Token to use when authorizing against the server [Use with
584 --list when unregistered].
585 --set=USAGE
588 Usage to apply to this system
589 --unset
592 Removes any previously set usage preference.
593 IMPORT OPTIONS
597 The import command imports and applies a subscription certificate for
598 the system which was generated externally, such as in the Customer Por‐
599 tal, and then copied over to the system. Importing can be necessary if
600 a system is preconfigured in the subscription management service or if
601 it is offline or unable to access the subscription management service
602 but it has the proper, relevant subscriptions attached to the system.
603 --certificate=CERTIFICATE_FILE
606 Points to a certificate PEM file which contains the subscription
607 certificate. This can be used multiple times to import multiple
608 subscription certificates.
609 REDEEM OPTIONS
612 The redeem command is used for systems that are purchased from third-
613 party vendors that include a subscription. The redemption process
614 essentially auto-attaches the preselected subscription that the vendor
615 supplied to the system.
616 --email=EMAIL
619 Gives the email account to send the redemption notification mes‐
620 sage to.
621 --locale=LOCALE
624 Sets the locale to use for the message. If none is given, then
625 it defaults to the local system's locale.
626 LIST OPTIONS
630 The list command lists all of the subscriptions that are compatible
631 with a system. The options allow the list to be filtered by subscrip‐
632 tions that are used by the system or unused subscriptions that are
633 available to the system.
634 --afterdate=YYYY-MM-DD
637 Shows pools that are active on or after the given date. This is
638 only used with the --available option.
639 --all Lists all possible subscriptions that have been purchased, even
642 if they don't match the architecture of the system. This is used
643 with the --available option.
644 --available
647 Lists available subscriptions which are not yet attached to the
648 system.
649 --consumed
652 Lists all of the subscriptions currently attached to the system.
653 --installed
656 Lists products which are currently installed on the system which
657 may (or may not) have subscriptions associated with them, as
658 well as products with attached subscriptions which may (or may
659 not) be installed. (default)
660 --ondate=YYYY-MM-DD
663 Sets the date to use to search for active and available sub‐
664 scriptions. The default (if not explicitly passed) is today's
665 date; using a later date looks for subscriptions which will be
666 active then. This is only used with the --available option.
667 --no-overlap
670 Shows pools which provide products that are not already covered;
671 only used with --available option.
672 --match-installed
675 Shows only subscriptions matching products that are currently
676 installed; only used with --available option.
677 --matches=SEARCH
680 Limits the output of --installed, --available and --consumed to
681 only subscriptions or products which contain SEARCH in the sub‐
682 scription or product information, varying with the list
683 requested and the server version.
684 SEARCH may contain the wildcards ? or * to match a single char‐
685 acter or zero or more characters, respectively. The wildcard
686 characters may be escaped with a backslash to represent a lit‐
687 eral question mark or asterisk. Likewise, to represent a back‐
688 slash, it must be escaped with another backslash.
689 --pool-only
692 Limits the output of --available and --consumed such that only
693 the pool IDs are displayed. No labels or errors will be printed
694 if this option is specified.
695 REFRESH OPTIONS
698 The refresh command pulls the latest subscription data from the server.
699 Normally, the system polls the subscription management service at a set
700 interval (4 hours by default) to check for any changes in the available
701 subscriptions. The refresh command checks with the subscription manage‐
702 ment service right then, outside the normal interval.
703 --force
706 Force regeneration of entitlement certificates on the server
707 before these certificates are pulled from the server.
708 ENVIRONMENTS OPTIONS
712 The environments command lists all of the environments that have been
713 configured for an organization. This command is only used for organiza‐
714 tions which have a locally-hosted subscription or content service of
715 some kind, like Subscription Asset Manager. The concept of environments
716 -- and therefore this command -- have no meaning for environments which
717 use the Customer Portal Subscription Management services.
718 --username=USERNAME
721 Gives the username for the account to use to connect to the
722 organization account.
723 --password=PASSWORD
726 Gives the user account password.
727 --token=TOKEN
730 Token to use when authorizing against the server.
731 --org=ORG
734 Identifies the organization for which to list the configured
735 environments.
736 REPOS OPTIONS
740 The repos command lists all of the repositories that are available to a
741 system. This command is only used for organizations which have a
742 locally-hosted content service of some kind, like Subscription Asset
743 Manager. With Red Hat's hosted content service, there is only one cen‐
744 tral repository.
745 --list Lists all of the repositories that are provided by the content
748 service used by the system.
749 --list-enabled
752 Lists all of the enabled repositories that are provided by the
753 content service used by the system.
754 --list-disabled
757 Lists all of the disabled repositories that are provided by the
758 content service used by the system.
759 --enable=REPO_ID
762 Enables the specified repository, which is made available by the
763 content sources identified in the system subscriptions. To
764 enable multiple repositories, use this argument multiple times.
765 Wild cards * and ? are supported.
766 --disable=REPO_ID
769 Disables the specified repository, which is made available by
770 the content sources identified in the system subscriptions. To
771 disable multiple repositories, use this argument multiple times.
772 Wild cards * and ? are supported.
773 ORGS OPTIONS
777 The orgs command lists all of the organizations which are available to
778 the specified user account. A multi-tenant infrastructure may have mul‐
779 tiple organizations within a single customer, and users may be
780 restricted to access only a subset of the total number of organiza‐
781 tions.
782 --username=USERNAME
785 Gives the username for the account to use to connect to the
786 organization account.
787 --password=PASSWORD
790 Gives the user account password.
791 --token=TOKEN
794 Token to use when authorizing against the server.
795 --serverurl=SERVER_HOSTNAME
798 Passes the name of the subscription service to use to list all
799 available organizations. The orgs command will list all organi‐
800 zations for the specified service for which the user account is
801 granted access. The default value, if this is not given, is the
802 Customer Portal Subscription Management service, https://sub‐
803 scription.rhsm.redhat.com:443. If there is an on-premise sub‐
804 scription service such as Subscription Asset Manager, this
805 parameter can be used to submit the hostname of the subscription
806 service, in the form [protocol://]servername[:port][/prefix].
807 For Subscription Asset Manager, if the Subscription Manager tool
808 is configured with the Subscription Asset Manager RPM, then the
809 default value for the --serverurl parameter is for the on-
810 premise Subscription Asset Manager server.
811 PLUGIN OPTIONS
815 The plugins command lists the available subscription-manager plugins.
816 --list List the available subscription-manager plugins.
819 --listslots
822 List the available plugin slots
823 --listhooks
826 List the available plugin slots and the hooks that handle them.
827 --verbose
830 Show additional info about the plugins, such as the plugin con‐
831 figuration values.
832 REPO-OVERRIDE OPTIONS
835 The repo-override command allows the user to manage custom content
836 repository settings
837 --repo The repository to modify (can be specified more than once)
840 --add=NAME:VALUE
843 Adds a named override with the provided value to repositories
844 specified with the --repo option
845 --remove=NAME
848 Removes a named override from the repositories specified with
849 the --repo option
850 --remove-all
853 Removes all overrides from repositories specified with the
854 --repo option
855 --list Lists all overrides from repositories specified with the --repo
858 option
859 IDENTITY OPTIONS
863 The identity command handles the UUID of a system, which identifies the
864 system to the subscription management service after registration. This
865 command can simply return the UUID or it can be used to restore the
866 registration of a previously-registered system to the subscription man‐
867 agement service.
868 --regenerate
871 Requests that the subscription management service issue a new
872 identity certificate for the system, using an existing UUID in
873 the original identity certificate. If this is used alone, then
874 the identity command also uses the original identity certificate
875 to bind to the subscription management service, using certifi‐
876 cate-based authentication.
877 --username=USERNAME
880 Gives the username for the account which is registering the sys‐
881 tem; this user account is usually tied to the user account for
882 the content delivery system which supplies the content.
883 Optional, for user-based authentication.
884 --password=PASSWORD
887 Gives the user account password. Optional, for user-based
888 authentication.
889 --token=TOKEN
892 Token to use when authorizing against the server.
893 --force
896 Regenerates the identity certificate for the system using user‐
897 name/password or token authentication. This is used with the
898 --regenerate option. --regenerate alone will use an existing
899 identity certificate to authenticate to the subscription manage‐
900 ment service. If the certificate is missing or corrupted or in
901 other circumstances, then it may be better to use user authenti‐
902 cation rather than certificate-based authentication. In that
903 case, the --force option requires the username or password or
904 token to be given either as an argument or in response to a
905 prompt.
906 FACTS OPTIONS
910 The facts command lists the system information, like the release ver‐
911 sion, number of CPUs, and other architecture information.
912 --list Lists the system information. These are simple attribute: value
915 pairs that reflect much of the information in the /etc/sysconfig
916 directory
917 cpu.architecture: x86_64
918 cpu.core(s)_per_socket: 1
919 cpu.cpu(s): 2
920 cpu.cpu_family: 6
921 cpu.cpu_mhz: 1861.776
922 cpu.cpu_op-mode(s): 64-bit
923 cpu.cpu_socket(s): 2
924 cpu.hypervisor_vendor: KVM
925 cpu.model: 2
926 cpu.numa_node(s): 1
927 cpu.numa_node0_cpu(s): 0,1
928 cpu.stepping: 3
929 cpu.thread(s)_per_core: 1
930 cpu.vendor_id: GenuineIntel
931 cpu.virtualization_type: full
932 distribution.id: Santiago
933 distribution.name: Red Hat Enterprise Linux Workstation
934 distribution.version: 6.1
935 ----
936 --update
940 Updates the system information. This is particularly important
941 whenever there is a hardware change (such as adding a CPU) or a
942 system upgrade because these changes can affect the subscrip‐
943 tions that are compatible with the system.
944 CLEAN OPTIONS
947 The clean command removes all of the subscription and identity data
948 from the local system without affecting the system information in the
949 subscription management service. This means that any of the subscrip‐
950 tions applied to the system are not available for other systems to use.
951 The clean command is useful in cases where the local subscription
952 information is corrupted or lost somehow, and the system will be re-
953 registered using the register --consumerid=EXISTING_ID command.
954 This command has no options.
957 CONFIG OPTIONS
960 The config command changes the rhsm.conf configuration file used by
961 Subscription Manager. Almost all of the connection information used by
962 Subscription Manager to access the subscription management service,
963 content server, and any proxies is set in the configuration file, as
964 well as general configuration parameters like the frequency Subscrip‐
965 tion Manager checks for subscriptions updates. There are major divi‐
966 sions in the rhsm.conf file, such as [server] which is used to config‐
967 ure the subscription management service. When changing the Subscription
968 Manager configuration, the settings are identified with the format sec‐
969 tion.name and then the new value. For example:
970 server.hostname=newsubscription.example.com
972 --list Prints the current configuration for Subscription Manager.
975 --remove=section.name
978 Deletes the current value for the parameter without supplying a
979 new parameter. A blank value tells Subscription Manager to use
980 service default values for that parameter. If there are no
981 defaults, then the feature is ignored.
982 --section.name=VALUE
985 Sets a parameter to a new, specified value. This is commonly
986 used for connection settings:
987 * server.hostname (subscription management service)
989 * server.proxy
991 * server.proxy_port
993 * server.proxy_user
995 * server.proxy_password
997 * rhsm.baseurl (content server)
999 * rhsm.certFrequency
1001 VERSION OPTIONS
1004 The version command displays information about the current Subscription
1005 Manager package, the subscription service the system is registered to
1006 (if it is currently registered), and the subscription management server
1007 that the system is configured to use. For example:
1008 [root@server ~]# subscription-manager version
1010 server type: Red Hat Subscription Management
1011 subscription management server: 0.9.18-1
1012 subscription management rules: 5.9
1013 subscription-manager: 1.12.1-1.git.28.5cd97a5.fc20
1014 python-rhsm: 1.11.4-1.git.1.2f38ded.fc20
1015 This command has no options.
1018 STATUS OPTIONS
1022 The status command shows the current status of the products and
1023 attached subscriptions for the system. If some products are not fully
1024 covered or subscriptions have expired, then the status command shows
1025 why subscriptions are not current and returns an error code.
1026 [root@server ~]# subscription-manager status
1028 +-------------------------------------------+
1029 System Status Details
1030 +-------------------------------------------+
1031 Overall Status: Current
1032 --ondate=DATE
1036 Shows the system status for a specific date in the future. The
1037 format of the date is YYYY-MM-DD.
1038 [root@server ~]# subscription-manager status --ondate=2014-01-01
1040 +-------------------------------------------+
1041 System Status Details
1042 +-------------------------------------------+
1043 Overall Status: Insufficient
1044 DEPRECATED COMMANDS
1047 As the structures of subscription configuration have changed, some of
1048 the original management commands have become obsolete. These commands
1049 have been replaced with updated commands.
1050 subscribe
1053 This has been replaced with attach. A similar registration
1054 option, --subscribe, has also be replaced with --auto-attach.
1055 unsubscribe
1058 This has been replaced with remove.
1059 activate
1062 This has been replaced with redeem.
1063
1066 subscription-manager has two major tasks:
1067 1. Handling the registration for a given system to a subscrip‐
1070 tion management service
1071 2. Handling the product subscriptions for installed products on
1074 a system
1075 subscription-manager makes it easier for network administrators to
1078 maintain parity between software subscriptions and updates and their
1079 installed products by tracking and managing what subscriptions are
1080 attached to a system and when those subscriptions expire or are
1081 exceeded.
1082 REGISTERING AND UNREGISTERING MACHINES
1086 A system is either registered to a subscription management service --
1087 which makes all of the subscriptions available to the system -- or it
1088 is not registered. Unregistered systems necessarily lack valid software
1089 subscriptions because there is no way to record that the subscriptions
1090 have been used nor any way to renew them.
1091 The default subscription management service in the Subscription Manager
1094 configuration is the Customer Portal Subscription Management service.
1095 The configuration file can be edited before the system is registered to
1096 point to an on-premise subscription management service like Subscrip‐
1097 tion Asset Manager.
1098 Systems are usually registered to a subscription management service as
1101 part of their initial configuration, such as the firstboot or kickstart
1102 process. However, systems can be registered manually after they are
1103 configured, can be removed from a content service, or re-registered.
1104 If a system has never been registered (not even during firstboot), then
1107 the register command will register the system with whatever subscrip‐
1108 tion management service is configured in the /etc/rhsm/rhsm.conf file.
1109 This command requires, at a minimum, the username and password or token
1110 for an account to connect to the subscription management service. If
1111 the credentials aren't passed with the command, then subscription-man‐
1112 ager prompts for the username and password interactively.
1113 When there is a single organization or when using the Customer Portal
1116 Subscription Management service, all that is required is the user‐
1117 name/password set or the token is used. For example:
1118 subscription-manager register --username=admin --password=secret or subscription-manager register --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo
1120 With on-premise subscription services, such as Subscription Asset Man‐
1123 ager, the infrastructure is more complex. The local administrator can
1124 define independent groups called organizations which represent physical
1125 or organizational divisions (--org). Those organizations can be subdi‐
1126 vided into environments (--environment). Optionally, the information
1127 about what subscription service (--serverurl) and content delivery net‐
1128 work (--baseurl) to use for the system registration can also be passed
1129 (which overrides the Red Hat Subscription Manager settings). The server
1130 and content URLs are usually configured in the Subscription Manager
1131 configuration before registering a system.
1132 subscription-manager register --username=admin --password=secret
1134 --org="IT Dept" --environment="local dev" --serverurl=local-cloudforms.example.com --baseurl=https://local-cloudforms.example.com:8088/cfFe
1135 If a system is in a multi-tenant environment and the organization is
1139 not provided with the registration request, registration fails with a
1140 remote server error. In the rhsm.log, there will be errors about being
1141 unable to load the owners interface.
1142 If a system is registered and then somehow its subscription information
1146 is lost -- a drive crashes or the certificates are deleted or corrupted
1147 -- the system can be re-registered, with all of its subscriptions
1148 restored, by registering with the existing ID.
1149 subscription-manager register --username=admin
1151 --password=secret --consumerid=1234abcd
1152 A system uses an SSL client certificate (its identity certificate) to
1155 authenticate to the subscriptions system to check for updates or
1156 changes to subscriptions. If the identity certificate is lost or cor‐
1157 rupted, it can be regenerated using the identity command.
1158 subscription-manager identity --regenerate
1160 Using the --force option will prompt for the username and password for
1163 the account, if one isn't given, and then return the new inventory ID
1164 and the hostname of the registered system.
1165 subscription-manager identity --force
1167 Username: jsmith
1168 Password:
1169 eff9a4c9-3579-49e5-a52f-83f2db29ab52 server.example.com
1170 A system is unregistered and removed from the subscription management
1174 service simply by running the unregister command. Unregistering a sys‐
1175 tem and removing its attached subscriptions can free up subscriptions
1176 when a system is taken offline or moved to a different department.
1177 subscription-manager unregister
1179 An option with registration, --auto-attach, will automatically attach
1182 the subscriptions pool which best matches the system architecture and
1183 configuration to the newly-registered system. This option attaches sub‐
1184 scriptions as part of the registration process, rather than separately
1185 managing subscriptions.
1186 subscription-manager register --username=admin --password=secret
1188 --auto-attach
1189 Auto-attach also supports an option to set a preferred service level
1192 with the selected subscriptions, the --servicelevel option. In this
1193 case, the --servicelevel option sets a preference that helps the auto-
1194 attach process select appropriate subscriptions. For example, if the
1195 preferred service level for a production server is premium, and there
1196 are three matching subscriptions with different service levels (none,
1197 standard, and premium), the auto-attach process selects the subscrip‐
1198 tion which offers a premium service level.
1199 subscription-manager register --username=admin --password=secret
1201 --auto-attach --servicelevel=premium
1202 LISTING, ATTACHING, AND REMOVING SUBSCRIPTIONS FOR PRODUCTS
1205 A subscription is essentially the right to install, use, and receive
1206 updates for a Red Hat product. (Sometimes multiple individual software
1207 products are bundled together into a single subscription.) When a sys‐
1208 tem is registered, the subscription management service is aware of the
1209 system and has a list of all of the possible product subscriptions that
1210 the system can install and use. A subscription is applied to a system
1211 when the system is attached to the subscription pool that makes that
1212 product available. A system releases or removes that subscription
1213 (meaning, it removes that subscription so that another system can use
1214 that subscription count).
1215 list command shows you what subscriptions are available specifically to
1218 the system (meaning subscriptions which are active, have available
1219 quantities, and match the hardware and architecture) or all subscrip‐
1220 tions for the organization. Using the --ondate option shows subscrip‐
1221 tions that are or will be active at a specific time (otherwise, it
1222 shows subscriptions which are active today).
1223 subscription-manager list --available --ondate=2012-01-31
1225 +-------------------------------------------+
1226 Available Subscriptions
1227 +-------------------------------------------+
1228 Subscription Name: Red Hat Enterprise Linux
1229 SKU: SYS0395
1230 Pool Id: 8a85f981302cbaf201302d899adf05a9
1231 Quantity: 249237
1232 Service Level: None
1233 Service Type: None
1234 Multi-Entitlement: No
1235 Starts: 01/01/2021
1236 Ends: 01/01/2022
1237 Machine Type: physical
1238 The list command can also be used to show what products you currently
1241 have installed, as a way of tracking what products you have versus what
1242 subscriptions you have on the system.
1243 subscription-manager list --installed
1245 +-------------------------------------------+
1247 Installed Product Status
1248 +-------------------------------------------+
1249 ProductName: Red Hat Enterprise Linux Server
1251 Product ID: 69
1252 Version: 6.3
1253 Arch: x86_64
1254 Status: Subscribed
1255 Started: 07/26/2012
1256 Ends: 08/31/2015
1257 The list can be filtered to only include products or subscriptions that
1260 match the query string provided to --matches option.
1261 subscription-manager list --installed --matches="*Server*"
1263 +-------------------------------------------+
1265 Installed Product Status
1266 +-------------------------------------------+
1267 ProductName: Red Hat Enterprise Linux Server
1269 Product ID: 69
1270 Version: 6.3
1271 Arch: x86_64
1272 Status: Subscribed
1273 Started: 07/26/2012
1274 Ends: 08/31/2015
1275 Attaching a subscription requires the ID for the subscription pool (the
1278 --pool option). For example:
1279 subscription-manager attach
1281 --pool=ff8080812bc382e3012bc3845da100d2
1282 As with the register command, the system can be auto-attached to the
1284 best-fitting subscriptions. This is the default action and is equiva‐
1285 lent to using the --auto option:
1286 subscription-manager attach
1288 Auto-attach also supports an option to set a preferred service level
1292 with the selected subscriptions, the --servicelevel option. In this
1293 case, the --servicelevel option sets a preference that helps the auto-
1294 attach process select appropriate subscriptions. For example, if the
1295 preferred service level for a production server is premium, and there
1296 are three matching subscriptions with different service levels (none,
1297 standard, and premium), the auto-attach process selects the subscrip‐
1298 tion which offers a premium subscription.
1299 subscription-manager attach --servicelevel=premium
1301 Some subscriptions define a count based on attributes of the system
1304 itself, like the number of sockets or the number of virtual guests on a
1305 host. You can combine multiple subscriptions together to cover the
1306 count. For example, if there is a four socket server, you can use two
1307 subscriptions for "RHEL Server for Two Sockets" to cover the socket
1308 count. To specify the number of subscriptions to use, use the --quan‐
1309 tity option. For example:
1310 subscription-manager attach
1312 --pool=ff8080812bc382e3012bc3845da100d2
1313 --quantity=2
1314 Removing subscription from a system releases the subscription back into
1317 the pool. The system remains registered with the subscription manage‐
1318 ment service. Each product has an identifying X.509 certificate
1319 installed with it. To remove a subscription for a specific product,
1320 specify the serial number (or numbers, in multiple --serial options) of
1321 the certificate:
1322 subscription-manager remove --serial=1128750306742160
1324 Giving the remove command with the --all option removes every subscrip‐
1327 tion the system has used.
1328 REDEEMING EXISTING SUBSCRIPTIONS
1332 Sometimes, a system may come preconfigured with products and subscrip‐
1333 tions. Rather than attaching a pool and claiming a subscription, this
1334 system simply needs to redeem its existing subscriptions.
1335 After registration, subscriptions on preconfigured systems can be
1338 claimed using the redeem command, which essentially auto-attaches the
1339 system to its preexisting subscriptions.
1340 subscription-manager redeem --email=admin@example.com --org="IT Dept"
1342 VIEWING LOCAL SUBSCRIPTION & CONTENT PROVIDER INFORMATION
1345 Red Hat has a hosted environment, through the Customer Portal, that
1346 provides centralized access to subscription management and content
1347 repositories. However, organizations can use other tools -- like Sub‐
1348 scription Manager -- for content hosting and subscription management.
1349 With a local content provider, the organization, environments, reposi‐
1350 tories, and other structural configuration is performed in the content
1351 provider. Red Hat Subscription Manager can be used to display this
1352 information, using the environments, orgs, and repos commands.
1353 subscription-manager repos --list
1355 subscription-manager environments --username=jsmith
1357 --password=secret --org=prod
1358 or
1360 subscription-manager environments --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo --org=prod
1362 subscription-manager orgs --username=jsmith
1365 --password=secret
1366 or
1368 subscription-manager orgs --token=eyJhbGciOiJSUzI1NiIsI ... stGc_2bFDQC8CENEOo
1370 CHANGING SUBSCRIPTION MANAGER CONFIGURATION
1373 The Subscription Manager CLI and GUI both use the /etc/rhsm/rhsm.conf
1374 file for configuration, including what content and subscription manage‐
1375 ment services to use and management settings like auto-attaching. This
1376 configuration file can be edited directly, or it can be edited using
1377 the config command. Parameters and values are passed as arguments with
1378 the config command in the format --section.parameter=value , where sec‐
1379 tion is the configuration section in the file: server, rhsm, rhsmcertd
1380 or logging.
1381 For example, to change the hostname of the subscription management ser‐
1384 vice host:
1385 subscription-manager config --server.hostname=myserver.example.com
1387 The entries in the logging section are somewhat special. The keys in
1390 this section are a name of a logger. The values are the logging level.
1391 Valid levels are one of: DEBUG , INFO , WARNING , ERROR , or CRITICAL
1393 Valid logger names are the full module path of any Subscription Manager
1395 module. For example: subscription_manager or subscription_manager.man‐
1396 agercli
1397 There are three main top-level loggers: subscription_manager, rhsm, and
1400 rhsm-app. All logger names begin with one of the above.
1401 To set the default log level for all loggers (that are not otherwise
1404 set in the logging section), edit the default_log_level key in
1405 /etc/rhsm/rhsm.conf
1406 UPDATING FACTS
1410 The information about a system, such as its hardware and CPU, its oper‐
1411 ating system versions, and memory, are collected by Subscription Man‐
1412 ager in a list of facts. Subscription Manager uses these facts to
1413 determine what purchased subscriptions are compatible with the system.
1414 Whenever these facts change (such as installing an additional CPU), the
1415 facts can be updated immediately using the facts command.
1416 subscription-manager facts --update
1418 The collected facts can also be overridden by creating a JSON file in
1420 the /etc/rhsm/facts/ directory. These have simple formats that define a
1421 fact and value:
1422 {"fact1": "value1","fact2": "value2"}
1424 Any fact override file must have a .facts extension.
1427 When these fact files are added, running the facts command will update
1430 the collected facts with the new, manual facts or values.
1431 SUBSCRIPTIONS AND KICKSTART
1434 The subscription-manager tool can be run as a post-install script as
1435 part of the kickstart installation process. This allows subscription
1436 management (registering and applying subscriptions) to be automated
1437 along with installation. For example:
1438 %post --log=/root/ks-post.log
1440 /usr/sbin/subscription-manager register --username admin --password secret --org 'east colo' --auto-attach --servicelevel=premium --force
1441
1444 The subscription-manager tool uses outgoing HTTPS requests. In the
1445 default configuration it will use HTTPS on port 443 to the subscription
1446 servers subscription.rhsm.redhat.com and to the content delivery ser‐
1447 vice cdn.redhat.com.
1448 For information about the network addresses that subscription-manager
1450 and the subscription-manager yum plugin use see https://access.red‐
1451 hat.com/site/solutions/59586
1452
1455 subscription-manager can be configured to use a proxy in several ways:
1456 * via standard HTTP_PROXY , HTTPS_PROXY , NO_PROXY environment
1458 variables (environment-level settings)
1459 * via options in /etc/rhsm/rhsm.conf (application-level set‐
1461 tings)
1462 * via command-line arguments (command-level overrides)
1464 Although subscription-manager respects environment variables for proxy
1467 configuration, this should be avoided in favor of the configuration
1468 file, because the daemons (ex. rhsmcertd ) do not provide ways to mod‐
1469 ify their environments.
1470 Each option of the proxy configuration (hostname, port, host/domain
1472 pattern blacklist, username, password) is read independently, with
1473 precedence being command-line over configuration over environment, and
1474 then the resulting set of options is used to configure the proxy con‐
1475 figuration.
1476 For example, if the HTTP_PROXY environment variable is set and no_proxy
1478 is set in /etc/rhsm/rhsm.conf then both are present in the effective
1479 proxy configuration.
1480 If two equivalent options are set in different places, then the prece‐
1482 dence determines which value is effective.
1483 For example, the NO_PROXY environment variable is set and the no_proxy
1485 configuration file option is set, then the value from the configuration
1486 file is the effective value.
1487
1490 * /etc/pki/consumer/*.pem
1491 * /etc/pki/entitlement/<serial>.pem
1493 * /etc/pki/product/*.pem
1495 * /etc/rhsm/rhsm.conf
1497 * /etc/rhsm/facts/*.facts
1499
1502 Deon Lackey, <dlackey@redhat.com>, and Pradeep Kilambi, <pkilambi@red‐
1503 hat.com>
1504 subscription-manager(8)