Token Management ---------------- 1. TOKENS VS. AUTHORIZATION CODES An authorization code: - enables a product to execute on a given cluster ID - is based only on the machine's cluster ID - cannot be used on another machine - does not move with an Environment backup - has an expiration data (which may be "forever") - belongs to the machine, not to individual users - by itself will let anyone on a non-tokenized machine use a product - by itself will not let anyone on a tokenized machine use a product - must have tokens as well A token: - allows a user to either login (session token) or use a layered product - is based on both the machine's cluster ID and site ID - can be transferred to other machines at the same site - moves with an Environment backup to a new machine (bug) - does not expire - are consumed by users, not by the machine - only appears on a tokenized machine - by itself will not let anyone use a product - must have authorization code as well 2. TOKENIZED VS. NON-TOKENIZED MACHINES - Series 100 machines cannot be on per-session support (are not "tokenized"), and therefore do not use tokens, but do have an authorization code for each product. - Series 200, 300 machines may or may not be tokenized: . If they are tokenized, they use both authorization codes and tokens. Most s200, s300 in the field are tokenized. . If they are not tokenized, they use only authorization codes. - A non-tokenized 200/300 is tokenized using a special procedure called Setup_Machine, which: . Establishes its site ID . Establishes the initial number of session tokens . Establishes the initial number of layered product tokens . Can only be run one time further changes to the site ID or tokens require a code from the home office (other than tokens transferred between machines at the same site by the customer). See the installation procedure for D2 (D_12_1_1) for instance, when tokens were introduced, or any later version for details on running Setup_Machine. - Series 400 machines are always tokenized, and therefore have both authorization codes and tokens. - How to tell if a machine is tokenized? . Confirm with Order Ops or Contracts. . Have the system administrator of the R1000 parc run procedure Show_Site. If a site ID is reported, it is tokenized. If it says the site ID has not been set, it is not tokenized. 3. LAYERED PRODUCT TOKENS - Layered product token names do not necessarily match the product names, but they do match the authorization code product names. For example: . product: RXI . authorization code and token: X Interface - Use procedure Show_Tokens to see valid token names. - As of D3 (D_12_6_5), RXI and RWI tokens are not checked--usage is limited by session tokens. - Some older layered products (and older versions of layered products) are not tokenized. - Layered product tokens are consumed when a user issues the first command which executes the product, and not released until the user logs out and all background jobs for the layered product have finished. However, there is a known limitation in the token release mechanism, and the layered product token is not released until the user logs back in, the next time when the token will be detected and released. So if user A uses a layered product token, and then logs out, and user B tries to use the same layered product token (i.e., there are no more tokens for the layered product available) before user A logs back in, the system will erroneously report that no tokens are available. The workaround is to run the Show_Tokens procedure when the message that no tokens are available comes up. Show_Tokens will find and release any unused tokens. - If the number of layered product tokens = the Buy_Out (or "golden") number, token checking is suppressed, i.e., there are unlimited layered product tokens available. - The Buy_Out number for each product can be found in a Rational Price Guide or by running the Show_Tokens procedure. 4. SESSION (LOGIN) TOKENS - There are 3 types of session tokens, depending on type of machine and type of support the machine is under: - Login tokens are used on Series 200 and Series 300 machines that are NOT under per-session support (i.e., tokenized, but still paying support under an old support contract allowing "golden" (unlimited tokens). - Full Session tokens are used on Series 400 machines and are under support at a higher rate than old 200/300 sessions. - Fundamental Session tokens are used on foreign(*) Series 400 machines and are under support at a higher rate than old 200/300 sessions. Originally in countries outside the US, CMVC does not come as part of the Environment and must be purchased separately. Think of it as: Full Session = Fundamental Session + CMVC Although CMVC must be purchased separately in these countries, CMVC is not tokenized (only has an authorization code), so CMVC must be purchased on an "all or none" basis. In practice, nearly all foreign customers purchase CMVC, so Fundamental Session can be thought of as equivalent to Full Session. - A machine may only have ONE type of token (it is not possible to "mix and match"). - Login tokens can be freely transferred to machines at the same site which use Login tokens. - Full/Fundamental Session tokens can be freely transferred to machines at the same site which use the same type of token. - Because Full and Fundamental Session tokens are "more expensive" than Login tokens, there are theoretical rules on transfers between the two types: . Full/Fundamental Session tokens can be transferred to machines at the same site which use Login tokens, but they become Login Sessions and cannot be converted back to Full/Fundamental Sessions. . Login Sessions may not be transferred to machines at the same site which use Full/Fundamental Sessions unless they are converted to the more expensive support. These are theoretical rules, because in practice, as of D3 (D_12_6_5), session tokens of any type may be transferred to machines at the same site, regardless of the session token type, and they will be automatically converted to the session token type used on the accepting machine. Note that if it is possible to go from Full/Fundamental Session -> Login, going in the opposite direction need to be explicitly authorized by contracts and are subjects to higher support rates. - A procedure, Convert_Tokens, is available to convert all the session tokens on a machine from one type to another, but require a special code generated by Order Ops. - Refer questions about support and token conversions to Order Ops and/or Contracts. 5. SITE IDs AND TOKEN TRANSFER - In order to transfer tokens between two machines, both machines must have the same site ID. - Use the procedure Show_Site to check site IDs. If it says one has not been set, the machine is not tokenized. (See section on "Tokenized vs. Non-tokenized machines".) - When Series 400 machines are set up for shipping in manufacturing, their site ID is set to be the same as the cluster ID, since we usually don't know whether they will be part of a site. - When most Series 200/300 machines were tokenized using Setup_Machine, the site ID was set the same as the cluster ID. - Contracts have rules as to what constitutes a "site". If a customer has machines that are located closely to one another and wishes to establish a site, they should contact Order Ops to verify that the site conditions are met and assign a common site ID for all the machines that qualify. - A common site ID has the form: NAMxxxxxx where: NAM is a 3-letter abbreviation for the customer xxxxxx is a 6-digit number for the site Most customers only have one site, so have site IDs such as HUC000001. Large customers may have multiple site IDs. - The procedure to change a site ID is called Set_Site, but requires a special code from Order Ops. 6. TOKEN TRANSFER PROCEDURE - Token transfer (either session tokens or layered product tokens) between machines with the same site ID is straightforward: . On the donating machine, run: Donate_Tokens (Product => ">>PRODUCT<<",Donation => 0, Resulting_Remote_Count => 0,Remote_Machine_Id => 0, Remote_Site => ">>SITE ID<<",Response => ""); For example: Donate_Tokens (Product => "Login",Donation => 8,Resulting_Remote_Count => 12,Remote_Machine_Id => 651226,Remote_Site => "HUC000001",Response => ""); which produces this output: 2003/06/02 10:49:45 ::: [Donate_Tokens ("Login", 8, 12, 651226, "HUC000001", 2003/06/02 10:49:45 ... "")]. 2003/06/02 10:49:46 +++ Donation of 8 tokens for Login has resulted in 12 2003/06/02 10:49:46 ... tokens. 2003/06/02 10:49:46 +++ Running Snapshot daemon. Run the following on the remote machine: Accept_Tokens (Product => "Login", Donation => 8,Resulting_Count => 12, Code => "66CEF2A8696A54C"); 2003/06/02 10:50:12 ::: [end of Donate_Tokens]. - Then run Accept_Tokens on the accepting machine: Accept_Tokens (Product => ">>PRODUCT NAME<<", Donation => 0, Resulting_Count => 0, Code => ">>AUTHORIZATION CODE<<", Authorization => "", Response => ""); WARNING: Alphabetic letters in the Code must be in all uppercase! Note: customers do not use the Authorization parameter. This is used for a transaction ID when tokens are assigned from Order Ops. (See section on "Token assignment for additional purchases".) The Accept_Tokens example above produces this output: 2003/06/02 14:04:01 ::: [Accept_Tokens ("Full Session", 8, 12, 2003/06/02 14:04:01 ... "66CEF2A8696A54C", "", "")]. 2003/06/02 14:04:02 +++ Full Session tokens set to 12. 2003/06/02 14:04:02 +++ Running Snapshot daemon. 2003/06/02 14:04:32 ::: [end of Accept_Tokens]. - Both Donate_Tokens and Accept_Tokens cause an immediate snapshot to be taken, so that tokens may not be improperly recovered. - The tokens are available immediately on the accepting machine. - There are restrictions to the usage of Donate_Tokens and Accept_Tokens: - Operator capability is required to run both Donate_Tokens and Accept_Tokens. - Machines that are not tokenized cannot run Donate_Tokens or Accept_Tokens. - The Donate_Tokens procedure will fail if it would leave the donating machine with a negative number of tokens. - The Accept_Tokens procedure must be run on the same calendar day as the Donate_Tokens procedure. If the transferred tokens are not accepted on the same day, they are permanently lost and cannot be recovered by the customer. They must have new tokens assigned by Order Ops. - The donating machine may not accept tokens of any kind on the same calendar day. - The accepting machine may not donate tokens of any kind on the same calendar day. - An easy way around the day restrictions is to change the system time temporarily, but we don't want to tell customers about this. - The donating machine has no way of verifying the site ID of the accepting machine. Therefore, if the wrong site ID is used in the Donate_Tokens procedure, the tokens will not be accepted and will be permanently lost. 7. TOKEN ASSIGNMENT FROM HOME OFFICE - If the customer purchases additional tokens or loses tokens by making a mistake in transferring them, Order Ops can generate codes, which will allow them to run Accept_Tokens and get the new tokens or correct the problem. - Prior to D2.2 (D_12_5_0), customers had to accept these assigned tokens on the same calendar day. Due to time differences and other contingencies, in order to prevent time planning constraints, we implemented a "transaction ID" scheme: - In addition to the Code parameter of Accept_Tokens, Order Ops generates a unique "transaction ID" which is entered in the Authorization parameter. - The transaction ID is date-independent, but when Accept_Tokens is run with a transaction ID, the transaction ID is stored and further attempts to rerun Accept_Tokens with the same transaction ID will fail. The Code parameter will still work, as long as Accept_Tokens is run on the same day the Code was generated. Remember to verify the timestamp on the machine before installing. 8. DIAGNOSTIC TOOLS - Show_Site gives the site ID. - Show_Tokens shows the tokenized products on the machine, and for each one: . the token name . the users currently consuming the tokens - the total number of tokens available (labeled Limit) - the number of tokens in use (labeled Current) - the Buy_Out (or "golden") number of tokens - if Limit = Buy_Out, then token checking is suppressed for that product, and unlimited tokens are available - Buy_Out should always be a non-zero value, but anecdotal evidences have shown there are instances where the token data structures have been altered and the Buy_Out is set to 0. We do not have the load procs available to reset the correct values anymore. 9. TOKENS AND ENVIRONMENT BACKUPS - The token configuration from a machine may be stored on an Environment backup and restored when the backup is restored, even if the backup is restored on a different machine (and even though the authorization codes will all be invalid). - This may be of surprise on sites where new machines are rebuilt with custom "template" backups, instead of the Environment loaded in Manufacturing. To correct this: . compare the tokens ordered with what was on the backup loaded, and use appropriate Donate_Tokens commands to get rid of extra tokens (donate them to cluster ID 999999 with same site ID to permanently lose them) . appropriate Accept_Tokens commands (with codes generated by Order Ops) to add missing tokens 10. TROUBLESHOOTING TOKEN PROBLEMS Questions to answer: - Is the machine(s) tokenized? (If so, Show_Site will give a site ID.) - Is the site ID correct on both the donating and accepting machines? - Are you running Donate_Tokens/Accept_Tokens from an account with operator capability? - Did you use the same name (and spelling) for the token type, as shown by Show_Tokens? (Be especially wary of "Full Session" (correct) vs. "Full_Session" (incorrect)) - Have you already donated or accepted tokens on this machine today? - What Environment version is running on the donating and accepting machines? - Does Show_Tokens show the token configuration expected? - Does Show_Tokens show a 0 Buy_Out value for any token type? - What is the exact error message received? - Has the Code parameter generated by Donate_Tokens been put in the Authorization parameter of Accept_Tokens (rather than in the Code parameter)? - Did you correctly use the Code and Authorization (transaction ID) parameters given by Order Ops or switched them? - Did you try to run Show_Tokens to release unused tokens? (If complaining about tokens being tied up by other users.) - Did the machine's Environment come from another machine's backup? - What type of session token do users consume when they login on the machine (check output of Show_Tokens)? - Has the machine been rebooted after using Convert_Tokens to change the system to a different session token type?