Manage2 API. by: J. Nick Koston

Transcription

1 Manage2 API by: J. Nick Koston Training Seminar 2006

2 Introduction! Hello, My name is Nick! This presentation is about the Manage2 API.! This also covers basic ideas behind our Manage2 system.! Our Manage2 system is a live system, so changes made on the system have immediate effects. Training Seminar 2006

3 Main Topics! Basic Manage2 Concepts! Installation of the Manage2 API Package! Basic use of the Manage2 API! Integration of the Manage2 API with your existing systems. Training Seminar 2006

4 Basic Concepts (Groups)! Groups are added through the Manage2 web interface.! Grouping is at your sole discretion.! By default, your account will have a group by the same as your company name.! Creating additional groups is for convenience.

5 Basic Concepts (Packages)! Packages are configured on your account by us. These are basically rate plans for a specific type of license. For example:! COMPANY-INTERNAL would be for your standard dedicated server.

6 Basic Concepts (Packages) COMPANY-EXTERNAL would be for your standard externally sold dedicated server (distributors only). More Samples:! COMPANY-INTERNAL-VPS! COMPANY-INTERNAL-WIN32

7 Basic Concepts (Packages)! Importance of setting the right package Determines Pricing Type of Server Setting the incorrect package may cause the license to auto expire (vps on non-vps), or be unusable (unix on win32).

8 Numeric IDs! Numeric IDs For quick access and long term substainability. Knowing the numeric id of an item can save time when working with the API.! Which items have numeric ids Packages Licenses Groups

9 Obtaining the Manage2 API Package! At the time of this document, the current version was 1.0 The latest version is listed at the top of your manage2 interface when you login. For a quick download,

10 Getting it Up and Running! Prerequisites *nix based system Perl or later Openssl & Development Libraries Perl Modules! Socket (base)! Carp (base)! Data::Dumper! XML::Simple! LWP::UserAgent! Net::SSLeay

11 Installation on a Non-cPanel Based Machine! The quickest way to get everything installed, is to first install cpanel's base script package.! cpanel's base script package is designed to operate on most *nix machines without a base cpanel install. Use of these scripts without cpanel is only permitted if you are a cpanel license holder.! In a root shell: cd ~ wget -O - tar -x -f - -j -v -C /

12 Installation! Installing the Prerequisites /scripts/ensurerpm openssl-devel /scripts/perlinstaller Data::Dumper XML::Simple LWP::UserAgent Net::SSLeay! Simple Install wget -O XMLCPL-1.0.tar.gz tar -f XMLCPL-1.0.tar.gz -z -x -v -C /usr/local (cd /usr/local;ln -s XMLCPL-1.0 XMLCPL)

13 Basic Use! The perl module is called 'cpanellicensing'! By default, we install in /usr/local/xmlcpl! If you'll be running your perl script outside of / usr/local/xmlcpl, you will need to add / usr/local/xmlcpl to the include path as shown: BEGIN { push(@inc,'/usr/local/xmlcpl'); }

14 Manage2 Security and Sub Accounts! Its not necessary to use your main manage2 account with the API.! You can create a sub-account with less privileges when logged in from your main account.! Sub accounts can be limited to only working with pre configured groups and packages. You can also limit viewing billing data.

15 The cpanellicensing Object! Constructing the object my $licensemanager = new cpanellicensing (user => 'YOURUSERNAME', pass=> 'YOUR- PASSWORD');! Your Username and Password are the ones you use to access Be sure to login to manage2 from the server that you will be using the API Package on before attempting to connect. You will need to do this so the ip address of the server will be added to the access list.

16 Methods for Obtaining License Data! fetchlicenses! fetchpackages! fetchgroups! fetchlicenseid

17 Methods: fetchlicenses! Returns a hash of all active licenses that you have access to.! fetchexpiredlicenses is also available. This method returns the same type of hash, but only shows licenses that are expired.

18 Methods: fetchgroups! Returns a hash of all groups that you have access to.

19 Methods: fetchpackages! Returns a hash of all packages that you have access to.

20 Methods: fetchlicenseid! Takes one argument: a hash with a single key called 'ip' with the ip address of the server to lookup! Returns a scalar with the license id (liscid).! Sample my $liscid = $licensemanager->fetchlicenseid(ip => ' ');

21 Methods for Processing Data! findkey

22 Methods: findkey! Convenience function! Used for a quick lookup of the packageid or groupid from the hashes returned from fetchpackages & fetchgroups respectively.! Two Arguments: Name to Lookup (scalar) Hash reference (from fetchgroups,fetchpackages)! Sample: $groupid = $licensemanager->findkey('samplegroup',\% GROUPS);

23 Methods for Manipulating Licenses! activatelicense! expirelicense! reactivatelicense

24 Methods: activatelicense! Activates a cpanel license on a given IP. OFAC compliance is required! Four Arguments ip: The Ip Address for the license. groupid: The Group Id your wish to add the license under (fetchgroups+findkey) packageid: The Package Id to use. (fetchpackages+findkey) force: Should a new license be added if one already exists? (overwrites discounts)

25 Methods: activatelicense! Sample: $licensemanager->activatelicense(ip => ' ',groupid => 256,packageid => 12,force => 0);! Quick Notes: You can lookup the Package Id, and Group Id every time with the fetchgroups+findkey and fetchpackages+findkey logic, but if you already know their numeric values, adding a license will be a lot faster.

26 Sample #1: Adding a License #!/usr/bin/perl use cpanellicensing; my $ip = $ARGV[0]; if ($ip!~ /^\d+\.\d+\.\d+\.\d+$/) { print "Usage: $0: <ip>"; } my $licensemanager = new cpanellicensing(user => ' [email protected] ', pass => ' YOURPASS '); #It might be prudent to include your username and password from some other file #outside of the web root if you are using this as part of a cgi script. my (%GROUPS) = $licensemanager->fetchgroups(); my (%PACKAGES) = $licensemanager->fetchpackages(); my $groupid = $licensemanager->findkey(' GROUPNAME ',\%GROUPS); my $packageid = $licensemanager->findkey(' PACKAGENAME ',\%PACKAGES); #Here we resolve the predetermined group name and package name to their numeric #equivalents. my $liscid = $licensemanager->activatelicense(ip => $ip, groupid => $groupid, packageid => $packageid, force => 1); print "Added license with id: ${liscid}\n";

27 Sample #1a: Adding a License with Numeric Ids #!/usr/bin/perl use cpanellicensing; my $ip = $ARGV[0]; if ($ip!~ /^\d+\.\d+\.\d+\.\d+$/) { print "Usage: $0: <ip>"; } my $licensemanager = new cpanellicensing(user => ' [email protected] ', pass => ' YOURPASS '); #It might be prudent to include your username and password from some other file #outside of the web root if you are using this as part of a cgi script. my $groupid = 12233; my $packageid = 254; #Here we already known which groupid and packageid to use so we can save some time by #not querying the server. my $liscid = $licensemanager->activatelicense(ip => $ip, groupid => $groupid, packageid => $packageid, force => 1); print "Added license with id: ${liscid}\n";

28 Methods: expirelicense! Sample: $licensemanager->expirelicense(liscid => 2000,reason => 'Customer switched to cpanel for win32');! Returns a numeric result Any value greater then zero indicated success! Quick Notes: You need to pass this license id (liscid) to this function, and not the ip address. You should use the fetchlicenseid function that we talked about earlier to get this id.

29 Methods: reactivatelicense! Sample: $licensemanager->reactivatelicense(liscid => 2000);! Returns a numeric result Any value greater then zero indicated success! Quick Notes: You need to pass this license id (liscid) to this function, and not the ip address. You should use the fetchlicenseid function that we talked about earlier to get this id.

30 Questions? Discussion? Ask away! Training Seminar 2006