Getting Started With VZAgent SOAP

Transcription

1 SWsoft, Inc. Getting Started With VZAgent SOAP Developer's Guide Version 3.0 (c)

2 ISBN: N/A SWsoft Inc Sunrise Valley Drive Suite 325 Herndon, VA USA Tel: +1 (703) Fax: +1 (703) Copyright by SWsoft, Inc. All rights reserved Distribution of this work or derivative of this work in any form is prohibited unless prior written permission is obtained from the copyright holder. Linux is a registered trademark of Linus Torvalds. Virtuozzo, Plesk, HSPcomplete, and corresponding logos are trademarks of SWsoft, Inc. Intel, Pentium, and Celeron are registered trademarks of Intel Corporation. Microsoft Windows, Windows 2003 Server, Windows XP, Windows 2000, Windows NT, Windows 98, Windows 95, Microsoft SQL Server, Microsoft Desktop Engine (MSDE), Microsoft Management Console are trademarks or registered trademarks of Microsoft Corporation IBM DB2 is a registered trademark of International Business Machines Corp. MegaRAID is a registered trademark of American Megatrends, Inc. PowerEdge is a trademark of Dell Computer Corporation.

3 3 Contents Preface 5 Documentation Conventions...5 Typographical Conventions...5 Shell Prompts in Command Examples...6 General Conventions...6 Feedback...6 Introduction 7 Key Features...7 Limitations...8 Installation...8 Using VZAgent SOAP 9 Choosing Project Type...9 Generating Code...9 Working With VZAgent...10 Start...10 Certificates Policy Preparation...11 Connection...11 Logging In and Creating Session...12 Fetching List of VPSs...14 Creating New VPS...15 Fetching VPS Configuration and Status...16 Starting and Stopping VPS...19 Downloading Files...21

4 Contents 4 Some Usage Patterns 24 SOAP Bindings...24 Optional Elements...25 Base Login Types...26 VZAgent Developer's Guide...26 Other SOAP Clients and Their Known Issues 27 Visual Basic.NET...27 Visual J#.NET...28 Apache Axis 1.2 for Java...28 Troubleshooting 29 Full C# Class Code 30 Index 36

5 5 C HAPTER 1 Preface In This Chapter Documentation Conventions... 5 Feedback... 6 Documentation Conventions Before you start using this guide, it is important to understand the documentation conventions used in it. For information on specialized terms used in the documentation, see the Glossary at the end of this document. Typographical Conventions The following kinds of formatting in the text identify special information. Formatting convention Triangular Bullet( ) Special Bold Italics Type of Information Step-by-step procedures. You can follow the instructions below to complete a specific task. Items you must select, such as menu options, command buttons, or items in a list. Titles of chapters, sections, and subsections. Used to emphasize the importance of a point, to introduce a term or to designate a command line placeholder, which is to be replaced with a real name or value. Monospace The names of commands, files, and directories. Preformatted On-screen computer output in your command-line sessions; source code in XML, C++, or other programming languages. Monospace Bold What you type, contrasted with onscreen computer output. Example To create a VPS: Go to the QoS tab. Read the Basic Administration chapter. These are the so-called EZ templates. To destroy a VPS, type vzctl destroy vpsid. Use vzctl start to start a VPS. Saved parameters for VPS 101 # rpm V virtuozzo-release CAPITALS Names of keys on the keyboard. SHIFT, CTRL, ALT

6 Preface 6 KEY+KEY Key combinations for which the user must press and hold down one key and then press another. CTRL+P, ALT+F4 Shell Prompts in Command Examples Command line examples throughout this guide presume that you are using the Bourne-again shell (bash). Whenever a command can be run as a regular user, we will display it with a dollar sign prompt. When a command is meant to be run as root, we will display it with a hash mark prompt: Bourne-again shell prompt $ Bourne-again shell root prompt # General Conventions Be aware of the following conventions used in this book. Chapters in this guide are divided into sections, which, in turn, are subdivided into subsections. For example, Documentation Conventions is a section, and General Conventions is a subsection. When following steps or using examples, be sure to type double-quotes ("), left singlequotes (`), and right single-quotes (') exactly as shown. The key referred to as RETURN is labeled ENTER on some keyboards. The root path usually includes the /bin, /sbin, /usr/bin and /usr/sbin directories, so the steps in this book show the commands in these directories without absolute path names. Steps that use commands in other, less common, directories show the absolute paths in the examples. Feedback If you spot a typo in this guide, or if you have thought of a way to make this guide better, we would love to hear from you! If you have a suggestion for improving the documentation (or any other relevant comments), try to be as specific as possible when formulating it. If you have found an error, please include the chapter/section/subsection name and some of the surrounding text so we can find it easily. Please submit a report by to userdocs@swsoft.com.

7 7 C HAPTER 2 Introduction Starting with Virtuozzo Linux and Virtuozzo Windows 3.0, VZAgent provides SOAP compatibility and can be used for running Web Services over the HTTP protocol. To access the VZAgent web services, you need just a few lines of code and no knowledge of SOAP or XML. All this is possible because there exists a wide range of frameworks and tools for generating code in various programming languages from the Web Service Definition Language (WSDL) schemas provided by VZAgent. This document describes the most basic steps for creating a C# client program in Visual Studio.NET for the.net framework. In This Chapter Key Features... 7 Limitations... 8 Installation... 8 Key Features Supports the full set of the VZAgent on-demand functionality, which covers the whole range of the services provided by VZAgent. Supports both the SOAP 1.1 and SOAP 1.2 protocols. Provides WSDL schemas for automatic code generation. Enables usage of a variety of external SOAP clients, including.net.

8 Introduction 8 Limitations SOAP in version of VZAgent has the following limitations: Works only with Virtuozzo Linux 2.6.1, Virtuozzo Windows 3.0, or higher version nodes. Operates only over the HTTPS protocol. Supports only the on-demand functionality (no notifications are available). Installation No installation as such is required. To access the VZAgent services, you need an installed Virtuozzo Linux or higher, or Virtuozzo Windows 3.0 or higher node and routing enabled between your client machine and the Service VPS of the Virtuozzo node. Once you have both, you can start using the services right away.

9 9 C HAPTER 3 Using VZAgent SOAP We're going to write our program in Visual Studio.NET and the C# language to illustrate how to use VZAgent SOAP. In This Chapter Choosing Project Type... 9 Generating Code... 9 Working With VZAgent Choosing Project Type You can use any kind of Visual Studio.NET C# project for your application. Your choice depends on your application requirements only. For our example, let's select a C# Windows Console Application and call it CSSoap. Generating Code To generate classes in Visual Studio, you need to use the Add Web Reference dialog box. The common procedure for adding a web reference to a project is as follows: 1 In Solution Explorer, select your project. 2 On the "Project" menu, choose "Add Web Reference". The Add Web Reference dialog box opens. 3 Type or copy and paste in the "URL" field of the dialog box the following URL: 4 Press the "Go" button. In the web services list, you will see a single entry: "1 Service Found: VZA". 5 Type the desired name for the web service in the "Web reference name" field. This name will be used in your code as the C# namespace to access the selected service. For our example, let the name be "VZA". 6 Press the "Add Reference" button. You'll see a new item called "VZA" appear under "Web References" in Solution Explorer.

10 Using VZAgent SOAP 10 Working With VZAgent Start Now you can start using the generated classes to access VZAgent services. For details on VZAgent and its components (we'll mention some of them, for example Operators, below), please consult the VZAgent Reference manual. At the beginning, you have the generated code in your Class1.cs file looking like this: Class1.cs: using System; namespace CSSoap /// <summary> /// Summary description for Class1. /// </summary> class Class1 /// <summary> /// The main entry point for the application. /// </summary> [STAThread] static void Main(string[] args) // // TODO: Add code to start application here // Console.Read(); We added "Console.Read()" at the end of Main() to let our window stay open until any key is pressed.

11 Using VZAgent SOAP 11 Certificates Policy Preparation Since VZAgent SOAP uses HTTPS as transport protocol, we have to deal with the certificate issues. For now, we're going to use Trust All Certificates Policy. We'll create a class that implements such a policy for us and pass it to the CertificatePolicy manager during login. Here is the class: // Class, used as a Certificate policy provider and allowing all certificates public class TrustAllCertificatePolicy : System.Net.ICertificatePolicy public TrustAllCertificatePolicy() cert, public bool CheckValidationResult(System.Net.ServicePoint sp, System.Security.Cryptography.X509Certificates.X509Certificate System.Net.WebRequest req, int problem) // Trust everything return true; Connection The VZAgent server listens for your SOAP requests on port This is the port with which your connection should be made. Note also that the connection should be redirected to the Service VPS of the server you're requesting a connection with. For our example, we'll use the URL

12 Using VZAgent SOAP 12 Logging In and Creating Session First of all, we'll have to log into VZAgent, let it authenticate us and create the session ID, which we'll be using for all the subsequent operations. Please keep in mind that a created session expires after some inactivity period (3 hours by default). Of course we have to know some VZAgent login credentials. The superuser login is "vzagent0". The password for this login you were asked to enter during the creation of the Service VPS on your Virtuozzo node. Let's suppose it is "mypassword" and use it here. // Function provides initial login to url with user and password private string Login(string url, string user, string password) // Allow any certificates. System.Net.ServicePointManager.CertificatePolicy = new TrustAllCertificatePolicy(); // Create a class, providing access to TicketM Operator of VZAgent. VZA.ticketmBinding ticketm = new VZA.ticketmBinding(); // Set up the server URL. ticketm.url = url; // Set up login credentials, using Encoding.GetBytes to convert password into byte array. VZA.login logincred = new VZA.login(); System.Text.Encoding ascii = System.Text.Encoding.ASCII; logincred.user = user; logincred.password = ascii.getbytes(password); // Use dummy packet header ticketm.packet_header = new VZA.packet_headerType(); // Invoke the login command. VZA.loginResponse lr = ticketm.login(logincred); // Return the resulting Session ID. return lr.ticket; The above function allows for initial login and returns the generated session ID. We'll invoke it from Main() and print out the result. The sequence of our operations will be invoked from the Run() function: private string m_sid; private string m_url; // Main Function for our test. public void Run() // Log in and store the resulting Session ID. m_sid = Login(" "vzagent0", "mypassword"); Console.WriteLine("Session ID: " + m_sid); We introduced the fields "m_sid" and "m_url" to store the connection data for future operations. Let also add exception handling to Main() and print out the exception text to the console:

13 Using VZAgent SOAP 13 static void Main(string[] args) // // TODO: Add code to start application here // Class1 VZAServer = new Class1(); try VZAServer.Run(); catch(system.web.services.protocols.soapexception ex) Console.WriteLine(ex.Code.ToString() + ", " + ex.message); Console.WriteLine("Details:" + ex.detail.innertext); catch(system.xml.xmlexception xmlex) Console.WriteLine(xmlex.ToString()); catch(system.invalidoperationexception opex) Console.WriteLine(opex.Message + "\n" + opex.innerexception); Console.Read(); Now you can compile and start your program. Your output should look like this: Session ID: vzagent c41b96ceet3768e77b If you see an error, please consult the Troubleshooting Section at the back of this document. To log out, you can use ticketmbinding::logout.

14 Using VZAgent SOAP 14 Fetching List of VPSs Let's begin using VZAgent services and accessing Virtuozzo. As a starter we'll fetch the list of the VPSs that exist on the server. This can be done with the "list_ve" command of the VZAgent HWM Operator. In SOAP-generated classes, the "list_ve" command corresponds to "hwmbinding.list_ve". We also need a helper function to initialize bindings, set up the URL and the session ID: // Initialize new binding with Url and session ID. private System.Object InitBinding(System.Type bindingtype) System.Object Binding = bindingtype.getconstructor(system.type.emptytypes).invoke(null); bindingtype.getproperty("url").setvalue(binding, m_url, null); VZA.packet_headerType header = new VZA.packet_headerType(); header.session = m_sid; bindingtype.getfield("packet_header").setvalue(binding, header); return Binding; Once we have this helper function, we can write the code for fetching: // Fetch VPS list private string FetchVPSList() // Initialize hwmbinding reflecting HWM Operator of VZAgent VZA.hwmBinding hwm = (VZA.hwmBinding)InitBinding(typeof(VZA.hwmBinding)); // Retrieving list of VPSes for an empty list of VEID, which means to retrieve the whole list. VZA.list_ve lve = new VZA.list_ve(); long[] lstve = hwm.list_ve(lve); // Serializing the resulting list into a string. String resp = ""; for (int i = 0; i < lstve.length; ++i) resp += "VEID:" + lstve[i] + "\n"; return resp; To invoke FetchVPSList(), we need to add it to the very end of Run(), our main function: // Fetch and write VPS list. Console.WriteLine("VPS list:"); Console.Write(FetchVPSList()); Finally, we start fetching the VPSs: Session ID: vzagent dc41b999eat449bc702 VPS list: VEID:1 VEID:101 VEID:102 VEID:103 VEID:104

15 Using VZAgent SOAP 15 VEID:105 VEID:200 VEID:301 VEID:444 VEID:517 VEID:520 VEID:777 Creating New VPS One of the most important parts of Virtuozzo hosting is VPS provisioning. There are various options for creating VPSs. Here we'll create a new VPS based on the existing VPS sample called "vps.basic" and let the VEID get allocated automatically: // Create VPS with VEID and based on specified VPS sample private string CreateVPS(long veid, string VPSSampleName) // Initialize vembinding reflecting VEM Operator of VZAgent VZA.vemBinding vem = (VZA.vemBinding)InitBinding(typeof(VZA.vemBinding)); // Parameters for VPS creation VZA.create1 param = new VZA.create1(); param.veid = veid; param.veidspecified = true; // Create based on a VPS sample with the specified name. param.item = VPSSampleName; // Creating VPS VZA.createResponse1 result = vem.create(param); // We're ok if no exception was generated. return "VPS create operation returned OK"; To call this function successfully from Run(), we need to pass it the next available VEID, i.e. the last fetched VEID plus one, and the sample configuration name: // Create a new VPS on a next available VEID and "vps.basic" sample. Console.WriteLine(); Console.WriteLine("Creating VPS " + m_lastveid.tostring() + " based on vps.basic sample."); Console.WriteLine(CreateVPS(m_lastVEID + 1, "vps.basic")); Here is the outcome of the above invocation: Creating VPS based on vps.basic sample. VPS create operation returned OK Alternatively, we could define a completely new configuration and then supply its name to "param.item" instead of VPSSampleName. Setting the configuration parameters might begin like this: // Custom configuration VPS creation. VZA.ve_configType config = new VZA.ve_configType(); config.hostname = "myhost"; config.ip = " "; config.os_template = "redhat-9"; // And so on

16 Using VZAgent SOAP 16 Fetching VPS Configuration and Status The next step we take is to fetch the VPS 101 configuration and status. This service is provided by the VEM Operator of VZAgent, so we'll use vembinding here. // Fetch VPS configurations and statuses private string FetchVPSInfo(long[] veids, bool statusesonly) // Initialize vembinding reflecting VEM Operator of VZAgent VZA.vemBinding vem = (VZA.vemBinding)InitBinding(typeof(VZA.vemBinding)); // Parameters structure ve_info VZA.ve_info veinfo = new VZA.ve_info(); if (!statusesonly) // Request to report whole configuration of VPS. There is a possibility to // narrow down the request set by specifying flags to "config" structure. veinfo.config = new VZA.ve_infoConfig(); else veinfo.config = null; // Request to report VPS status. veinfo.status = new Object(); // VEIDs of VPSes we'd like to get information for. veinfo.veid = veids; // The request itself. Result is stored into ves array. VZA.veType[] ves = vem.ve_info(veinfo); // Serialization of the result into a string. Not all available fields are // serialized in this example. String resp = ""; for (int i = 0; i < ves.length; i++) VZA.veType ve = ves[i]; String VEText; VEText = "VEID:"; VEText += ve.veid; VEText += "\n"; if (!statusesonly) VEText += "Hostname:" + ve.config.hostname + "\n"; VEText += "State:"; VEText += ve.status.state; VEText += "\n"; VEText += "Transition:"; VEText += ve.status.transition; VEText += "\n"; if (!statusesonly) // Serialization of QOSes. for (int j = 0; j < ve.config.qos.length; j++) VZA.qosType qos = ve.config.qos[j]; VEText += "QoS:"; VEText += qos.id; VEText += " Soft:"; VEText += qos.soft; VEText += " Hard:"; VEText += qos.hard; VEText += "\n"; VEText += "\n";

17 Using VZAgent SOAP 17 resp += VEText; return resp; The function above takes the list of VEIDs as the first parameter and fetches the configurations and statuses of the respective VPSs. Here you can see that the parameter passed to "vem.ve_info" is a structure that we previously initialized with several values. Those values define the optional flags that can be chosen during the method call. They include "status" and "config". Their presence in the code tells VZAgent that it must return the VPS status and/or VPS configuration, respectively. As far as the "status" flag is concerned, it is a simple element that can be present or not. That's why we can initialize it with any object (in our case "new Object()"), and the.net XML engine will serialize it into an empty XML element. In contrast, "config" is a more complex type: it can hold a structure of other flags indicating which configuration fields we want to retrieve. In our case, we decided to fetch the whole configuration and, therefore, left the "config" structure empty. The "statusesonly" flag is added for future use. It will allow us to fetch only statuses if we need to check them. After the method call, we serialize the result into the string that will be returned by this function. Of course the Run() function should be modified: // Fetch and write VPS 101 and 102 configurations and statuses. long[] veids = 101, 102; Console.WriteLine(); Console.WriteLine("VPS 101 and 102 configurations and statuses:"); Console.Write(FetchVPSInfo(veids, false)); The output returned by FetchVPSInfo is as follows: VPS 101 and 102 configurations and statuses: VEID:101 Hostname:myhost State:running Transition: QoS:avnumproc Soft:40 Hard:40 QoS:numproc Soft:65 Hard:65 QoS:numtcpsock Soft:80 Hard:80 QoS:numothersock Soft:80 Hard:80 QoS:vmguarpages Soft:6144 Hard: QoS:kmemsize Soft: Hard: QoS:tcpsndbuf Soft: Hard: QoS:tcprcvbuf Soft: Hard: QoS:othersockbuf Soft: Hard: QoS:dgramrcvbuf Soft: Hard: QoS:oomguarpages Soft:200 Hard:300 QoS:lockedpages Soft:32 Hard:32 QoS:shmpages Soft:8192 Hard:8192 QoS:privvmpages Soft:22528 Hard:24576 QoS:numfile Soft:1280 Hard:1280 QoS:numflock Soft:100 Hard:110 QoS:numpty Soft:16 Hard:16 QoS:numsiginfo Soft:256 Hard:256 QoS:dcachesize Soft: Hard: QoS:physpages Soft:0 Hard: QoS:numiptent Soft:128 Hard:128 QoS:diskspace Soft: Hard: QoS:diskinodes Soft: Hard:220000

18 Using VZAgent SOAP 18 QoS:quotatime Soft:0 Hard:0 QoS:cpuunits Soft:0 Hard:1000 QoS:cpulimit Soft:0 Hard:100 QoS:quotaugidlimit Soft:0 Hard:30000 VEID:102 Hostname:osiefus State:down Transition: QoS:avnumproc Soft:40 Hard:40 QoS:numproc Soft:65 Hard:65 QoS:numtcpsock Soft:80 Hard:80 QoS:numothersock Soft:80 Hard:80 QoS:vmguarpages Soft:6144 Hard: QoS:kmemsize Soft: Hard: QoS:tcpsndbuf Soft: Hard: QoS:tcprcvbuf Soft: Hard: QoS:othersockbuf Soft: Hard: QoS:dgramrcvbuf Soft: Hard: QoS:oomguarpages Soft:6144 Hard: QoS:lockedpages Soft:32 Hard:32 QoS:shmpages Soft:8192 Hard:8192 QoS:privvmpages Soft:22528 Hard:24576 QoS:numfile Soft:1280 Hard:1280 QoS:numflock Soft:100 Hard:110 QoS:numpty Soft:16 Hard:16 QoS:numsiginfo Soft:256 Hard:256 QoS:dcachesize Soft: Hard: QoS:physpages Soft:0 Hard: QoS:numiptent Soft:128 Hard:128 QoS:diskspace Soft: Hard: QoS:diskinodes Soft: Hard: QoS:quotatime Soft:0 Hard:0 QoS:cpuunits Soft:0 Hard:1000 QoS:cpulimit Soft:0 Hard:100 QoS:quotaugidlimit Soft:0 Hard:0

19 Using VZAgent SOAP 19 Starting and Stopping VPS Let's do some action now. As you can remember from the previous example, VPS 102 is in the "down" state. We'll restart it and then stop it again. Our next functions are called StartVPS and StopVPS and take a VEID as a parameter. // Start VPS with specified VEID. private string StartVPS(long veid) // Initialize vembinding reflecting VEM Operator of VZAgent VZA.vemBinding vem = (VZA.vemBinding)InitBinding(typeof(VZA.vemBinding)); // Paremeters structure VZA.start param = new VZA.start(); // Set up the veid param.veid = veid; // Start VPS VZA.startResponse2 result = vem.start(param); // We're ok if no exception was generated. return "VPS start operation returned OK"; // Stop VPS with specified VEID private string StopVPS(long veid) // Initialize vembinding reflecting VEM Operator of VZAgent VZA.vemBinding vem = (VZA.vemBinding)InitBinding(typeof(VZA.vemBinding)); // Paremeters structure VZA.stop param = new VZA.stop(); // Set up the veid param.veid = veid; // Stop VPS VZA.stopResponse2 result = vem.stop(param); // We're ok if no exception was generated. return "VPS stop operation returned OK"; The two functions above simply start and stop the specified VPS. We will add them to Run() and check the VPS status after calling each function: // Start and stop VPS 102 long[] startstopveids = 102; Console.WriteLine(); // Start VPS 102 Console.WriteLine(StartVPS(startStopVeids[0])); //Check VPS 102 status Console.WriteLine("VPS 102 status:"); Console.Write(FetchVPSInfo(startStopVeids, true)); //Stop VPS 102 Console.WriteLine(StopVPS(startStopVeids[0])); // Check VPS 102 status Console.WriteLine("VPS 102 status:"); Console.Write(FetchVPSInfo(startStopVeids, true)); Here is the output: VPS start operation returned OK

20 VPS 102 status: VEID:102 State:running Transition: VPS stop operation returned OK VPS 102 status: VEID:102 State:down Transition: Using VZAgent SOAP 20

21 Using VZAgent SOAP 21 Downloading Files Now, we'll try something different. Let's download some files. Below is the function that will help us with this: // Download files from specified VPS private string DownloadFiles(long veid, string[] paths) // Initialize vembinding reflecting VEM Operator of VZAgent VZA.filemBinding filem = (VZA.filemBinding)InitBinding(typeof(VZA.filemBinding)); // Paremeters structure. VZA.download files = new VZA.download(); // Set up the veid of VPS, we're downloading files from. files.veid = veid; // We'll be downloading in Packet Mode. files.packet_mode = new Object(); // Initialize list of files structures. files.file = new VZA.downloadFile[paths.Length]; System.Text.Encoding ascii = System.Text.Encoding.ASCII; for (int n = 0; n < paths.length; n++) files.file[n] = new VZA.downloadFile(); // Conversion from string to array of bytes. files.file[n].path = ascii.getbytes(paths[n]); // Downloading the files. VZA.fileType[] content = filem.download(files); // Serializing the result. String resp = ""; for (int n = 0; n < paths.length; n++) resp += "File : " + paths[n] + "\n"; resp += ascii.getstring(content[n].body); resp += "\n"; return resp; This function takes as arguments the VEID of the VPS, from which we will be downloading files, and a list of file paths. To retrieve the results, we need to set the packet mode on because its alternative, the VZAgent stream mode, cannot be supported here. After all the necessary parameters are initialized, we invoke the download() function and store the result in the "content" array. Finally, we parse the array elements to translate the contents of each file into a string, ready for output. As an example, let's try downloading the files "/etc/passwd" and "/etc/shadow" from VPS 102. These files contain user and group credentials on Linux. By the way, we shouldn't forget to restart VPS 102, because we left it in the "down" state. Below are the lines that we have to add to our Run() function: // Download files // Start VPS 102 Console.WriteLine(StartVPS(startStopVeids[0]));

22 Using VZAgent SOAP 22 // Download files "/etc/passwd" and "/etc/shadow" from VPS 102 string[] files = "/etc/passwd", "/etc/shadow"; Console.WriteLine("Downloading files"); Console.WriteLine(DownloadFiles(102, files)); And here is the download result: VPS start operation returned OK Downloading files File : /etc/passwd root:x:0:0:root:/root:/bin/bash bin:x:1:1:bin:/bin:/sbin/nologin daemon:x:2:2:daemon:/sbin:/sbin/nol adm:x:3:4:adm:/var/adm:/sbin/nologi lp:x:4:7:lp:/var/spool/lpd:/sbin/no sync:x:5:0:sync:/sbin:/bin/sync shutdown:x:6:0:shutdown:/sbin:/sbin halt:x:7:0:halt:/sbin:/sbin/halt mail:x:8:12:mail:/var/spool/mail:/s news:x:9:13:news:/etc/news: uucp:x:10:14:uucp:/var/spool/uucp:/ operator:x:11:0:operator:/root:/sbi games:x:12:100:games:/usr/games:/sb gopher:x:13:30:gopher:/var/gopher:/ ftp:x:14:50:ftp User:/var/ftp:/sbin nobody:x:99:99:nobody:/:/sbin/nolog vcsa:x:69:69:virtual console memory rpm:x:37:37::/var/lib/rpm:/bin/bash apache:x:48:48:apache:/var/www:/sbi webadmin:x:500:500::/home/webadmin: popa3d:x:84:84::/dev/null:/dev/null named:x:25:25:named:/var/named:/sbi mailnull:x:47:47::/var/spool/mqueue smmsp:x:51:51::/var/spool/mqueue:/s sshd:x:74:74:privilege-separated SS rpc:x:32:32:portmapper RPC user:/:/ pcap:x:77:77::/var/arpwatch:/sbin/n majordomo:x:91:91:majordomo List Ma File : /etc/shadow root:8robiw9ml7e9q:12654:0:99999:7: bin:*:12529:0:99999:7::: daemon:*:12529:0:99999:7::: adm:*:12529:0:99999:7::: lp:*:12529:0:99999:7::: sync:*:12529:0:99999:7::: shutdown:*:12529:0:99999:7::: halt:*:12529:0:99999:7::: mail:*:12529:0:99999:7::: news:*:12529:0:99999:7::: uucp:*:12529:0:99999:7::: operator:*:12529:0:99999:7::: games:*:12529:0:99999:7::: gopher:*:12529:0:99999:7::: ftp:*:12529:0:99999:7::: nobody:*:12529:0:99999:7::: vcsa:!!:12529:0:99999:7::: rpm:!!:12529:0:99999:7::: apache:!!:12529:0:99999:7::: webadmin:!!:12529:0:99999:7::: popa3d:!!:12529:0:99999:7:::

23 named:!!:12529:0:99999:7::: mailnull:!!:12529:0:99999:7::: smmsp:!!:12529:0:99999:7::: sshd:!!:12529:0:99999:7::: rpc:!!:12529:0:99999:7::: pcap:!!:12529:0:99999:7::: majordomo:!!:12613:::::: Using VZAgent SOAP 23

24 24 C HAPTER 4 Some Usage Patterns Below are some tips and tricks that might make your life easier when using VZAgent SOAP. In This Chapter SOAP Bindings Optional Elements Base Login Types VZAgent Developer's Guide SOAP Bindings The.NET SOAP client generates the key classes with the "Binding" postfix, e.g. filembinding, vembinding, sembinding. Each of them contains the methods provided by the equivalent VZAgent Operator: "filem", "vem", "sem", respectively. The VZAgent Reference Guide can be used as the knowledge base for the existing VZAgent services. Please keep in mind that only the on-demand operators, including the System Operator, are supported at the moment.

25 Some Usage Patterns 25 Optional Elements The VZAgent protocol provides a number of optional elements. In the generated code, you can encounter them as primitive types (e.g. "int" or "bool"), complex types (e.g. strings, classes or structures) or arrays. A primitive type element in an incoming or outgoing packet is usually flagged by a corresponding "bool" element just below it. The name of the latter is made of the name of the former and the "Specified" postfix. As an example, let's take a look at the "usertype" class: public class usertype /// <remarks/> public usertypeinitial_group initial_group; /// <remarks/> [System.Xml.Serialization.XmlElementAttribute("group")] public usertypegroup[] group; /// <remarks/> public int uid; /// <remarks/> [System.Xml.Serialization.XmlIgnoreAttribute()] public bool uidspecified; /// <remarks/> public string shell; /// <remarks/> [System.Xml.Serialization.XmlElementAttribute(DataType="base64Binary") ] public System.Byte[] password; /// <remarks/> public string home_dir; /// <remarks/> public string name; /// <remarks/> public string comment; /// <remarks/> [System.Xml.Serialization.XmlArrayItemAttribute("ve_range", typeof(ve_listtypeve_range), IsNullable=false)] [System.Xml.Serialization.XmlArrayItemAttribute("veid", typeof(long), IsNullable=false)] public object[] ve_list; You can see that the "uid" and "uidspecified" class members form a pair: the latter indicates that the former is present in the data.

26 Some Usage Patterns 26 The majority of the other fields in the "usertype" class belong to complex types, e.g. the "comment" string. Complex type elements can be absent in both requests to VZAgent and responses from it if they were not specified for a particular user. In those cases, the complex type elements can be set to "null" or left unset: the.net SOAP engine won't serialize or deserialize them. Finally, arrays, e.g. the "group" field, are considered optional and - if they are empty - not included in packets. The arrays that contain some elements will be present in packets. Base64 Because XML is text-based, not all ASCII characters are allowed to be passed as clear text. That's why some elements of the VZAgent protocol are of base64-encoded type. In C#, elements of this kind are represented as byte arrays. You shouldn't additionally encode data meant for those arrays - just fill them with the necessary content. Here is an example: VZA.login logincred = new VZA.login(); System.Text.Encoding ascii = System.Text.Encoding.ASCII; logincred.user = user; logincred.password = ascii.getbytes(password); Login Types In addition to the "vzagent0" superuser account, other non-superuser accounts can be created with the help of Virtuozzo Management Console and used for connection and operations. In the "Personal Edition Manager" folder, under Hardware Node, use the context menu in the "Service VPS Users" subfolder to create a new user and the "VPS Access" tab to assign some virtual environments to him/her. Under this user account, you will be able to log in and access the allowed services, mostly concerned with the assigned VPSs. VZAgent Developer's Guide You can find most of the documentation and examples in the VZAgent Developer's Guide. It contains the reference to the whole VZAgent interface, including message examples in XML. Note that classes generated from WSDL are exact copies of their XML counterparts described in XML Schemas of VZAgent. Therefore you can find the same names and fields in the generated classes as in the XML types. Let's take a look at the "vembinding::start" operation. You can see that the "start" command of the "vem" operator, which is described in the Ondemand Operators chapter of the Developer's Guide, takes the "veid" parameter, the same one that we provided in our example above. Further in the On-demand Operators chapter, you will find the description of other operators, most of which are defined in the WSDL services.

27 27 C HAPTER 5 Other SOAP Clients and Their Known Issues In This Chapter Visual Basic.NET Visual J#.NET Apache Axis 1.2 for Java Visual Basic.NET.NET WSDL and XML parsers still have many bugs. Some of them prevent seamless usage of classes generated from VZA.wsdl. After you add and try to compile the Web Reference from you'll see five compilation errors: four "Keyword does not name a type" errors and one "Reference to a non-shared member requires an object reference" error. The first four errors are caused by name conflicts between the user-defined identifiers and VB keywords. Usually parsers enclose the identifiers that are identical to VB keywords in square brackets. Note, however, that this does not work for words like "new", which are encountered in WSDL and XSDs. In our case, there are problems with the "get", "stop", "set" and "select" function names. To solve them, simply double click on each error line in the Task list and enclose the respective words in square brackets. The last error is related to the case-insensitive nature of VB: it confuses the "system" field name in the VZAgent "cpu_loadtype" class with its own "System" module. To fix this problem, change the line <System.Xml.Serialization.XmlIgnoreAttribute()> _ to <Xml.Serialization.XmlIgnoreAttribute()> _ Now you should have the code that compiles and works. The first group of these problems does not exist in the Visual Studio 2005 Beta, but you still have to delete "System" from "Xml.Serialization.XmlIgnoreAttribute()" manually.

28 Other SOAP Clients and Their Known Issues 28 Visual J#.NET Unfortunately, the current implementation of Visual J# in Visual Studio.NET 2003, due to its internal bugs, doesn't work with our WSDL. However, it works seamlessly with the Visual Studio 2005 Beta. Apache Axis 1.2 for Java For this client, we have one tip that reveals hidden knowledge of how to work with certificates: System.setProperty("org.apache.axis.components.net.SecureSocketFactory ",org.apache.axis.components.net.sunfaketrustsocketfactory"); The code above uses a fake trust manager trusting all certificates. This Java SOAP client also worked for us.

29 29 C HAPTER 6 Troubleshooting I cannot connect to the server with one of the following errors: The underlying connection was closed: Unable to connect to the remote server. Check your URL, port and routing to your server. VZAgent responded with error Details: 2704 Authentication failure - either user name or password is incorrect Check your login and password. Somewhere in the middle of an operation, I get the following error: VZAgent responded with error Details: 1004 Error invoking vzctl utility: VE is already running Check the state of your VPS that is used for the current operation. In the example above, you try to start VPS 112 and get the error message. This kind of error may occur when you are starting a VPS that is already in the "running" state. You can stop this particular server with the "vzctl stop 112" command from the command-line interface or use Virtuozzo Management Console for the same purpose. I'm using SOAP with.net Web Services and I get the following error: An unhandled exception of type 'System.Net.WebException' occurred in system.web.services.dll Additional information: The operation has timed-out..net SP1 has the default timeout value for the XML Web service calls set to ms. To avoid this problem, set the appropriate timeout value or set the timeout value to infinite, as shown in the following example: MyService service1 = new MyService(); service1.timeout = -1; /* infinite timeout */

30 30 C HAPTER 7 Full C# Class Code Here is the full text of our test class. Class1.cs using System; namespace CSSoap /// <summary> /// Summary description for Class1. /// </summary> class Class1 /// <summary> /// The main entry point for the application. /// </summary> [STAThread] static void Main(string[] args) // // TODO: Add code to start application here // Class1 VZAServer = new Class1(); try VZAServer.Run(); catch(system.web.services.protocols.soapexception ex) Console.WriteLine(ex.Code.ToString() + ", " + ex.message); Console.WriteLine("Details:" + ex.detail.innertext); catch(system.xml.xmlexception xmlex) Console.WriteLine(xmlex.ToString()); catch(system.invalidoperationexception opex) Console.WriteLine(opex.Message + "\n" + opex.innerexception); Console.Read(); private string m_sid; private string m_url; private long m_lastveid; // Class, used as a Certificate policy provider and allowing all certificates public class TrustAllCertificatePolicy : System.Net.ICertificatePolicy public TrustAllCertificatePolicy()

31 Full C# Class Code 31 cert, public bool CheckValidationResult(System.Net.ServicePoint sp, System.Security.Cryptography.X509Certificates.X509Certificate System.Net.WebRequest req, int problem) // Trust everything return true; // Main Function for our test. public void Run() // Log in and store the resulting Session ID. // To login, you will need to use the password you were asked // to enter during the creation of the Service VPS on your // Virtuozzo node. For now, let's assume it's "mypassword" and // pass it as the last parameter to Login() m_url = " m_sid = Login(m_url, "vzagent0", "mypassword"); Console.WriteLine("Session ID: " + m_sid); // Fetch and write VPS list. Console.WriteLine(); Console.WriteLine("VPS list:"); Console.Write(FetchVPSList()); // Create a new VPS on a next available VEID and "vps.basic" sample. Console.WriteLine(); Console.WriteLine("Creating VPS " + m_lastveid.tostring() + " based on vps.basic sample."); Console.WriteLine(CreateVPS(m_lastVEID + 1, "vps.basic")); // Fetch and write VPS 101 and 102 configurations and statuses. long[] veids = 101, 102; Console.WriteLine(); Console.WriteLine("VPS 101 and 102 configurations and statuses:"); Console.Write(FetchVPSInfo(veids, false)); // Start and stop VPS 102 long[] startstopveids = 102; Console.WriteLine(); // Start VPS 102 Console.WriteLine(StartVPS(startStopVeids[0])); //Check VPS 102 status Console.WriteLine("VPS 102 status:"); Console.Write(FetchVPSInfo(startStopVeids, true)); //Stop VPS 102 Console.WriteLine(StopVPS(startStopVeids[0])); // Check VPS 102 status Console.WriteLine("VPS 102 status:"); Console.Write(FetchVPSInfo(startStopVeids, true)); // Download files // Start VPS 102 Console.WriteLine(StartVPS(startStopVeids[0]));

32 Full C# Class Code 32 // Download files "/etc/passwd" and "/etc/shadow" from VPS 102 string[] files = "/etc/passwd", "/etc/shadow"; Console.WriteLine("Downloading files"); Console.WriteLine(DownloadFiles(102, files)); // Function provides initial login to url with user and password private string Login(string url, string user, string password) // Allow any certificates. System.Net.ServicePointManager.CertificatePolicy = new TrustAllCertificatePolicy(); // Create a class, providing access to TicketM Operator of VZAgent. VZA.ticketmBinding ticketm = new VZA.ticketmBinding(); // Set up the server URL. ticketm.url = url; // Set up login credentials, using Encoding.GetBytes to convert password into byte array. VZA.login logincred = new VZA.login(); System.Text.Encoding ascii = System.Text.Encoding.ASCII; logincred.user = user; logincred.password = ascii.getbytes(password); // Use dummy packet header ticketm.packet_header = new VZA.packet_headerType(); // Invoke the login command. VZA.loginResponse lr = ticketm.login(logincred); // Return the resulting Session ID. return lr.ticket; // Initialize new binding with Url and session ID. private Object InitBinding(System.Type bindingtype) System.Object Binding = bindingtype.getconstructor(system.type.emptytypes).invoke(null); bindingtype.getproperty("url").setvalue(binding, m_url, null); VZA.packet_headerType header = new VZA.packet_headerType(); header.session = m_sid; bindingtype.getfield("packet_header").setvalue(binding, header); return Binding; // Fetch VPS list private string FetchVPSList() // Initialize hwmbinding reflecting HWM Operator of VZAgent VZA.hwmBinding hwm = (VZA.hwmBinding)InitBinding(typeof(VZA.hwmBinding)); // Retrieving list of VPSes for an empty list of VEID, which means to retrieve the whole list. VZA.list_ve lve = new VZA.list_ve();

33 Full C# Class Code 33 long[] lstve = hwm.list_ve(lve); // Serializing the resulting list into a string. String resp = ""; for (int i = 0; i < lstve.length; ++i) resp += "VEID:" + lstve[i] + "\n"; // We'll remember last VEID for future use in CreateVPS method. m_lastveid = lstve[lstve.length -1]; return resp; // Create VPS with VEID and based on specified VPS sample private string CreateVPS(long veid, string VPSSampleName) // Initialize vembinding reflecting VEM Operator of VZAgent VZA.vemBinding vem = (VZA.vemBinding)InitBinding(typeof(VZA.vemBinding)); // Parameters for VPS creation VZA.create1 param = new VZA.create1(); param.veid = veid; param.veidspecified = true; // Create based on a VPS sample with the specified name. param.item = VPSSampleName; // Creating VPS VZA.createResponse1 result = vem.create(param); // We're ok if no exception was generated. return "VPS create operation returned OK"; // Fetch VPS configurations and statuses private string FetchVPSInfo(long[] veids, bool statusesonly) // Initialize vembinding reflecting VEM Operator of VZAgent VZA.vemBinding vem = (VZA.vemBinding)InitBinding(typeof(VZA.vemBinding)); // Paremeters structure ve_info VZA.ve_info veinfo = new VZA.ve_info(); if (!statusesonly) // Request to report whole configuration of VPS. There is a possibility to // narrow down the request set by specifying flags to "config" structure. veinfo.config = new VZA.ve_infoConfig(); else veinfo.config = null; // Request to report VPS status. veinfo.status = new Object(); // VEIDs of VPSes we'd like to get information for. veinfo.veid = veids; // The request itself. Result is stored into ves array. VZA.veType[] ves = vem.ve_info(veinfo);

34 Full C# Class Code 34 // Serialization of the result into a string. Not all available fields are // serialized in this example. String resp = ""; for (int i = 0; i < ves.length; i++) VZA.veType ve = ves[i]; String VEText; VEText = "VEID:"; VEText += ve.veid; VEText += "\n"; if (!statusesonly) VEText += "Hostname:" + ve.config.hostname + "\n"; VEText += "State:"; VEText += ve.status.state; VEText += "\n"; VEText += "Transition:"; VEText += ve.status.transition; VEText += "\n"; if (!statusesonly) // Serialization of QOSes. for (int j = 0; j < ve.config.qos.length; j++) VZA.qosType qos = ve.config.qos[j]; VEText += "QoS:"; VEText += qos.id; VEText += " Soft:"; VEText += qos.soft; VEText += " Hard:"; VEText += qos.hard; VEText += "\n"; VEText += "\n"; resp += VEText; return resp; // Start VPS with specified VEID. private string StartVPS(long veid) // Initialize vembinding reflecting VEM Operator of VZAgent VZA.vemBinding vem = (VZA.vemBinding)InitBinding(typeof(VZA.vemBinding)); // Paremeters structure VZA.start param = new VZA.start(); // Set up the veid param.veid = veid; // Start VPS VZA.startResponse2 result = vem.start(param); // We're ok if no exception was generated. return "VPS start operation returned OK"; // Stop VPS with specified VEID private string StopVPS(long veid) // Initialize vembinding reflecting VEM Operator of VZAgent VZA.vemBinding vem = (VZA.vemBinding)InitBinding(typeof(VZA.vemBinding)); // Paremeters structure

35 Full C# Class Code 35 VZA.stop param = new VZA.stop(); // Set up the veid param.veid = veid; // Stop VPS VZA.stopResponse2 result = vem.stop(param); // We're ok if no exception was generated. return "VPS stop operation returned OK"; // Download files from specified VPS private string DownloadFiles(long veid, string[] paths) // Initialize vembinding reflecting VEM Operator of VZAgent VZA.filemBinding filem = (VZA.filemBinding)InitBinding(typeof(VZA.filemBinding)); // Paremeters structure. VZA.download files = new VZA.download(); // Set up the veid of VPS, we're downloading files from. files.veid = veid; // We'll be downloading in Packet Mode. files.packet_mode = new Object(); // Initialize list of files structures. files.file = new VZA.downloadFile[paths.Length]; System.Text.Encoding ascii = System.Text.Encoding.ASCII; for (int n = 0; n < paths.length; n++) files.file[n] = new VZA.downloadFile(); // Conversion from string to array of bytes. files.file[n].path = ascii.getbytes(paths[n]); // Downloading the files. VZA.fileType[] content = filem.download(files); // Serializing the result. String resp = ""; for (int n = 0; n < paths.length; n++) resp += "File : " + paths[n] + "\n"; resp += ascii.getstring(content[n].body); resp += "\n"; return resp;

36 36 Index A Apache Axis 1.2 for Java 28 B Base64 26 C Certificates Policy Preparation 11 Choosing Project Type 9 Connection 11 Creating New VPS 15 D Documentation Conventions 5 Downloading Files 21 F Feedback 6 Fetching List of VPSs 14 Fetching VPS Configuration and Status 16 Full C# Class Code 30 G General Conventions 6 Generating Code 9 I Installation 8 Introduction 7 K Key Features 7 L Limitations 8 Logging In and Creating Session 12 Login Types 26 O Optional Elements 25 Other SOAP Clients and Their Known Issues 27 P Preface 5 S Shell Prompts in Command Examples 6 SOAP Bindings 24 Some Usage Patterns 24 Start 10 Starting and Stopping VPS 19 T Troubleshooting 29 Typographical Conventions 5 U Using VZAgent SOAP 9 V Visual Basic.NET 27 Visual J#.NET 28 VZAgent Developer's Guide 26 W Working With VZAgent 10