Howto: ModernBill Plugin for SCInterface

From SCInterface Wiki

Revision as of 21:59, 26 June 2008 by Admin (Talk | contribs)
(diff) ←Older revision | Current revision (diff) | Newer revision→ (diff)
Jump to: navigation, search

The following documentation is to provide assistance with configuring the Modernbill module for SCInterface. Support for Modernbill is provided by Parallels.

Contents

Terminology

Here are the meanings of some terms (sorted in alphabetical order) mentioned in this document where the definition may be otherwise unknown or ambiguous.

  • DS / Dedicated Server : see Host. This term is often used by Datacenters and Server Providers that will resell access to a host while managing the external requirements (space, electricity, ip network connectivity) and sometimes (but not always) the host operating system.
  • Game type : Type of application server, such as 'Counter-Strike Source' or 'Battlefield 2'. Also see SConnector
  • Host: Physical or Virtual PC with an installed operating system. This is typically a container for applications or game servers.
  • GS/Game Server : application running on a host, instance of a game type. Something like "Bill's BF2 Server"
  • GSP / Game Serv(ice|er) Provider : Resellers of Game Servers (and sometimes Dedicated Servers)
  • Modernbill / ModernBill / MB : The billing system into which you're trying to integrate your SCInterface Network : http://www.modernbill.com
  • Network : Usually SCInterface Network, but depending on context could also mean your host and its Network-Layer peers (as defined by the OSI)
  • Panel : Same as Modernbill's definition : Instance of the SCInterface module in Modernbill's Server Groups. This relates to 1 SCInterface user on a given SCInterface Network (and address/port of the SCM to get into that SCInterface Network)
  • SCInterface : The game server control product in it's entirety, including the UI, the SCManager and SController components (but not necessarily the actual deployment) http://www.scinterface.com
  • SC / SController / SCInterface Controller : Software agent that sits on the targeted host to enable SCInterface to control it.
  • SCM / SCManager / SCInterface Control Manager : Entrypoint for a UI into a SCInterface Network. Software agent that manages everything in your SCInterface Network. This is sometimes synonymous with SCInterface Network as you typically have one SCManager per SCInterface Network, but there may be multiple SCMs in the same network.
  • SCInterface Network : what you see if you login to a SCInterface UI as system admin : The list of Users, SCMs, SCs, Game Servers as they are configured.
  • SConnector / Driver : Configurations in SCInterface that define how SCInterface interacts with a game server or SController of a given type. (see Game Type)
  • SCUser / SCInterface User : your user in a SCInterface Network. Can also mean the username used to login as that user on that network.
  • Server : see GS / GameServer
  • UI : SCInterface User Interface. An interface for your users to interact with a SCInterface Network. This plugin enables Modernbill to act as a UI to interact with your SCInterface Network.

Documentation

Prerequisites

The following prerequisites must be met before downloading and installing the SCInterface module for ModernBill.

  1. Purchase, download and install SCInterface v2.0 or later.
  2. Purchase, download and install ModernBill v5.2 or later.
  3. Determine how you are going to be selling servers within SCInterface (from Typical Server Group Use Cases). Choose one of the following scenarios:
  4. Next, download and install the SCInterface module for ModernBill.

Install ModernBill's SCInterface Module

As of ModernBill v5.2, SCInterface is included with the latest distribution. Please skip to the next section to continue with the configuration of ModernBill with SCInterface.

  1. Download the latest version of ModernBill from http://www.modernbill.com. The SCInterface plugin is included in the latest ModernBill release. If you do not have this plugin available within your ModernBill installation, please contact ModernBill at http://www.modernbill.com to obtain the latest version.
  2. Enable the plugin within ModernBill. SCInterface v2.0 or later supports ModernBill.

For Developers Only - Using downloaded tar archive

The following is for developers and testing only. Regular users should download the latest release of ModernBill from http://www.modernbill.com. Contact SCInterface to download a developer version of the ModernBill module at http://www.scinterface.com.

  • Using Subversion
    1. Navigate to your modernbill installation folder : cd /var/www/modernbill
    2. Checkout the SCInterface module and api : svn co svn://svn.scinterface.com/mb_plugin/trunk .
  • Using downloaded tar archive
    1. Navigate to your installation folder : cd /var/www/modernbill
    2. Extract archive : tar -xzvf scinterface_mb_plugin.tar.gz

Configure Server Group

  1. Create Server Group:
  2. Add Servers
    1. From the System => Server Settings => Server Group Settings area, select SCInterface as your panel module (pull down when adding your first server in the SG) then hit the 'add' button.
    2. Important Fields:
      • SCInterface Admin Username : This is the username that modernbill will use when communicating with your SCManager to manage servers on this panel. This will be the owner of all the users created by modernbill on that SCInterface Network.
        • You might want to create a subuser of your main administrator user (sysadmin) in SCInterface to manage your Modernbill accounts. Put that username there. Make sure the user has SC, SCM and User Wide permissions.
      • SCInterface Admin Password : The password that goes with that Username when signing into SCInterface
      • SCManager Address : the IP address or hostname to your SCM.
      • SCManager Port : the tcp port that the SCM is listening on. Unless otherwise notified, leave to default 51026
      • Maximum Server Weight : The value here depends on the weight of the products that are sold. If you are reselling SC Credits and a credit has a weight of 1, then you might want to put the maximum number of credits you would like to / can sell. If / when SCInterface can't process a new account because of limits being exceeded (no free dedicated servers, no available SC credits, etc..), the modernbill event will fail so the package will not become active.

Typical Server Group Use Cases

This section determines how you are going to be selling servers within SCInterface (from Typical Server Group Use Cases). Choose one of the following scenarios:

  1. Dedicated Server Reseller - An entire instance of SCInterface (UI, SCM, or SC)
  2. SC License Reseller - A server that is managed by a central UI and SCM
  3. Game Server Reseller - An application on a server that is managed by a central UI, SCM. The end user can only manage their application and not the entire server

SC License Reseller

  1. Create an account in SCInterface to be your master modernbill user
  2. Assign the number of credits you'd like to resell to that user (in SCInterface)
  3. Set the maximum weight in modernbill to the value of licenses you want to resell
    1. The number of current accounts should always equal your total number minus the amount of credits available to your admin user in SCInterface, so at first, set it to 0
  4. In modernbill, create your sccredit package and assign it a weight of 1
  5. Notes:
    • In this scenario, the client's SCInterface user is assigned 1 SC credit (for each package), will own the SC and suspending or cancelling/deleting the package will attempt to remove 1 credit by first trying to remove an unused credit from the user, then from any of his children, then will find an SC to disable, disable it to make a credit available and then remove that credit.

SC License Reseller for multiple SCInterface Networks/Locations

  1. Follow the SC License Reseller steps for each SCInterface Network
  2. Depending on your modernbill product configuration, load balancing may already be configured

Dedicated Server Reseller

  1. Create an account in SCInterface to be your Dedicated Server Reseller user.
    • This could potentially be a child of a SC License reseller on this modernbill install or other modernbill install
  2. Create a SController for each dedicated server in SCInterface, and install the SController software on each.
    • Your modernbill admin user must own the SCs in SCInterface in order for the modernbill plugin to resell them
  3. Create a dedicated server package to represent what you're reselling.
    • Again, if you assign a weight of 1 in the package, you can use modernbill to limit the number of DServers to resell, and if there are no available dedicated servers, the modernbill event will fail telling you so, and the package will not become active.
  4. Notes:
    • In this scenario, the ownership of the SC will and must remain the admin's
    • Buying a package : modernbill will pick the first SC it finds that no subuser of the admin user has privs to (in other words unused), and that isn't disabled and assign all privs to the user.
    • Suspend : The SC will be disabled, all SCInterface applications running on this server will be stopped/killed. The user will still see the server on his SCInterface screen, but in a disabled state.
    • Unsuspend : The SC will be enabled (a.k.a un-disabled)
    • Cancel/Delete : All of the applications on the SC will be removed, including killing all the game servers, removing all the installations, making it ready to be re-sold. User will be stripped of his SCInterface privileges, so will not see it in SCInterface anymore.

Reselling a mix of Dedicated Servers

  1. If your server group contains SCs of different platforms, create a 'platform' attribute for your package or create a custom attribute in your widget/order form (pull-down/radio button ?) and have the value(s) match that of the SC in SCInterface. By default, your choices are 'windows', 'linux' and 'bsd'. If you don't have a 'platform' parameter or leave it empty, SCInterface will consider all available SCs. (You can still use the next option to differentiate between linux and windows Dedicated Servers)
  2. Similarly to platforms, if you have SCs from different locations (as defined in SCInterface) and you'd like to differentiate using that parameter, have an attribute called 'location' that contains the location you'd like to use. Do note that all sub-locations will be included, so if your product asks for 'World - North America - USA', that will include all the SCs in Usa, Usa-east, Usa-west and so on. Like 'platform', leaving blank or unset will make it so that all SCs are considered.
  3. If you would like to differentiate your dedicated servers by some other category, be it hardware-based : P4s in one, dual Xeons in another and give your user the granularity, then the easiest way would be to create a panel in your server group to represent that, and have the panel's admin user be the SCInterface user owning the SCs of that sub-group. Then assign that server to the package in the 'server group selection',

Game Server Reseller

  1. Create your admin account in SCInterface. Note that this user cannot own the SC (to differentiate from Dedicated Server Reselling). Setting ownership of an SC to a sub-user of this admin user doesn't remove 'ownership' privileges, so using the main 'sysadmin' user will not work here.
    • This also means that the game server reseller could be using dedicated servers bought from a dedicated server reseller.
  2. Configure your Servers
    1. Similar to dedicated-server reselling, make sure that the SController software is running on there and configured in SCInterface.
    2. The SC must be owned by some other user, but your modernbill user must have admin privs to the SC.
  3. Notes / Modernbill actions:
    1. The ownership of the game server in SCInterface must remain the panel admin's. The client will be assigned config, start, stop and status privileges. (all except admin and bypass_disabled)
    2. package create / buy : The game server will be created in SCInterface as well as installed on the host server. SCInterface will use the host/SC of the same platform as the apptype you configured for the package but that has the least usage on it (metric is something like 10+number of slots for each applications installed on there where the number of slots > 0). The user will be assigned all privs on the server except for admin and 'bypass_disable', meaning that disabling the GS in SCInterface will effectively disable the game server.
      • As an example, if you have a host with a 16-slot CS server and a 32-slot BF2 server, and another host with a 48-slot CS server as well as a 0-slot web server, your first SC will be assigned a usage metric of 68 (10+16+10+32) where the second server would be assigned a metric of 58 (10+48). The second host would then be selected.
    3. suspend : the game server will be stop/killed and then disabled in SCInterface. The user will still see the server, but with a nice red status light next to it.
    4. unsuspend : the game server will be re-enabled in SCInterface, the user can then resume operations
    5. cancel/delete : the server will be k-leened (stopped, then the files will be deleted). The server will also be removed from SCInterface

Create Product, Order Form and Widget

Creating Products - Follow the steps in there, they will guide you to create your order forms and widgets and everything else.

Stuff that matters:

  • Product
    1. Server Group should be the one you've just created for SCInterface
    2. Addon product : no
    3. Domain stuff : no , suppress, N/A
    4. Attributes :
      • Notes
        1. Listings below will be in 'attribute name' => 'attribute value' format. If in 'single quotes', the value must be used verbatim (exactly how it's written), otherwise, an explanation should guide you in the right direction for what to put there.
        2. Creating product attribute : when in the product configuration/edit area, go into the 'attributes' section and add from the 'Generic Attributes' section.
        3. Where you would like your product to encompass multiple types of something and leave that choice to the customer (where there is a choice) such as platform ('windows' versus 'linux'), or game type ('Battlefield 2' vs. 'Counter-Strike'), it may be advantageous to research into Modernbill on how to create custom form attributes and associate with different billing (16 slot public to be cheaper than a 32-slot public, etc..). The module doesn't care where it gets the info from as long as it gets it.
      • SC Credits
        1. 'type' => 'sccredit'
      • Dedicated Servers
        1. 'type' => 'dedicatedServer'
        2. 'serverid' => leave empty
        3. 'location' => optionally set to location name as seen in SCInterface (navigate to your SC's admin view/edit area to see your options)
        4. 'platform' => optionally set to 'linux', 'windows' or 'bsd'
      • Game Servers
        1. 'type' => 'gameServer'
        2. 'serverid' => leave empty
        3. 'appTypeID' => the game type's numerical ID
          • You can fetch the appTypeID from SCInterface by browsing to the SConnector listing and finding the numerical value next to the SConnector or gameType you'd like to use.
        4. 'maxPlayers' => whatever value makes sense for that/these type of game server(s).

Frequently Asked Questions / FAQ

  1. How can I reuse the same SCInterface user for multiple products/packages ?
    • The SCInterface plugin will try to use whatever information it gets from the order, so ultimately this is managed by ModernBill. In case of conflict (the proposed username already exist, but doesn't appear to be a customer of the current panel, SCInterface will automatically try adding digits until it is able to create the new user.
    • WARNING: If the service username provided matches someone else's username under the same panel/server, then that user will be reused, and thus gain access to your product. It is your duty as a modernbill administrator to make sure this doesn't happen. A quick way would be to use the client's modernbill username as a prefix for the service username on SCInterface.
  2. How can I change the SCInterface user assigned with my package?
    1. Suspend the package in modernbill
    2. Find/Create a suitable SCInterface user to own the package
      • Very important: This user must be a child of the administrator user that this package is assigned to, so unless you're reassigning the package to a different panel, this new user would have the same parent user as the original packageUsername.
    3. In the package attributes section, edit the 'packageUsername' attributes or any traces or your old username (there will be multiple, make sure to get them all).
    4. SCInterface alterations:
      • SC Credit : nothing to be done
      • Dedicated server or Game Server : remove privs from old user, and assign to new user
    5. Unsuspend package
  3. How can I switch panels (in modernbill)?
    • Don't, unless you are an expert ModernBill and SCInterface administrator. This has not been tested, but is what the author expects needs to be done. We don't support this as things can get complicated really quickly here. You have been warned.
    1. Suspend package in ModernBill
    2. Make SCInterface Changes
      1. User transfer
        • Same SCInterface Network, different Panel admin and SCInterface User only has this package
          1. Make user's parent the new panel admin user
        • Else
          1. Create new user on new panel (on panel's SCInterface User Interface , owned by panel's admin user)
      2. Server Transfer
        • SC Credit : nothing to do
        • Dedicated Server
          • Same dedicated server, same SCInterface Network, different panel admin
            1. assign ownership of the SC to the new panel owner
          • New Dedicated Server
            1. Delete all game servers on old DS
            2. Remove privs from user on that SC
            3. Remove the 'disabled' check in the SC's edit area to make this Dedicated server available.
            4. Assign all privs on new SC to the user. If you're switching to a DS/SC managed by a different panel, you may need to create a new SCInterface user and use that new user.
    3. Make ModernBill reassignments/changes
      1. Reassign panel : you'll find this option in the package's details area
      2. Package attributes to update
        1. packageUsername : this must match the SCInterface username of the package owner.
        2. serverID : this package attribute must match that of the Dedicated Server or Game Server in SCInterface (nothing for sccredits). Easiest way is to look at the appID or serverID parameter in the url when looking at the server's config screen.
    4. Unsuspend package
    5. Double-check SCInterface configurations :
      • SCCredits : if same user as before, user should have same number of total credits, and at least 1 available SC credit (and potentially a disabled SC). Otherwise, old user should have been stripped of credit and new user should now have an extra unused SC credit.
      • Dedicated Server
        1. Different Server : old server should not be disabled, should not have any apps installed on it and no sub-users should have privs to it. (should be available to be re-used by the plugin)
        2. Same Server : Server should not be disabled, and new user should have all privs assigned to it.
      • Game Server
        1. Similar to Dedicated server, except for a Game Server and privs should be all except admin and bypass_disabled.

Troubleshooting

  1. The package creation event fails, and it's SCInterface's fault (but i don't know for sure)
    1. Go into the event view, and look at the event output (MBAPI Command Output) for that errored event. The details of the error should be easily found in there, as well as recommendations on how to fix the situation.
    2. Typically :
      1. Client user creation may fail with 'access denied' if your admin user doesn't have any credits or SCs to resell
      2. for SC Credits : your admin user doesn't have any available credits left. Assign some more by increasing your number of SC Credits in SCInterface. (Buy more licenses and/or assign more credits in user admin area)
      3. for Dedicated Servers : no available servers to resell.
      4. for Game Servers : no available hosts for your appType. You're reselling a windows games but you only have linux hosts or something of the sort.
    3. The 'Mbapi Output' is empty. Try 'Debug Run' and investigate from the output shown on your screen.
  2. My client's package was assigned to someone else as a result of modernbill reusing an already-existing SCInterface user
    1. Follow the 'How can I change the SCInterface user' procedure from the FAQ
Retrieved from "http://wiki.scinterface.com/index.php/Howto:_ModernBill_Plugin_for_SCInterface"