Plugin example. Adding a new S3 storage

In the ispmanager panel, you can create a custom plugin that will allow you to:

• add your provider's new S3 storage for backup;
• automate the backup configuration process. 

Plugin configuration

1. Log in to the panel with a superuser account.
2. Navigate to the File Manager section.
3. Create and edit an XML file and a handler file.
4. Go to the Backup copies section.
5. In the toolbar, click Backup settings.
6. In Storage Type, select the New Storage option.

   

   It is not necessary to fill in the empty fields of the settings form.
   
   
7. Follow the link on the banner:

   

   After clicking the link, the server address provides information for accessing the new storage and makes a backward transition to the panel. The form fields in the panel are filled in automatically.

   Details

    A link template is used to switch back to the panel:

   https://<ip>:1500/ispmgr?startformdrawer=backup2.settings&starttab=backup2.superlist&storage_type=<storage type>&url_s3=<storage url>&id_amazon=<key identifier>&secret_amazon=<secret key>&s3_storage_class=<storage class>&bucket_addressing_model=<bucket addressing model>&s3_auto_region=<define bucket region automatically>&s3_region=<bucket region>

   Values that are inserted from the created XML file and handler file:

   • storage_type=<storage type> — defines values for the Storage Type drop-down list. If the storage is changed, access to the current backups is lost. To restore access, revert to the previous storage type. Default: stype_new value if it has not been replaced before.
   • url_s3=<storage URL> — link for API requests to the storage. Mandatory to be filled in.
   • id_amazon=<key identifier> — field Key Identifier. Mandatory to be filled in.
   • secret_amazon=<secret key> — field Secret key. Mandatory to be filled in.
   • s3_storage_class=<storage class> — defines values for the Storage class drop-down list. Available values:
     • sclass_DEFAULT — value Default;
     • sclass_STANDARD — value Standard;
     • sclass_STANDARD_IA — value Cold;
     • sclass_GLACIER — value Glacier.
     If your cloud service does not support the specified storage classes, download errors may occur.
     
     
   • bucket_addressing_model=<bucket addressing model> — defines values for the Bucket addressing model drop-down list. Available values:
     • subdomain — subdomain value. Accesses the bucket using a link of the following kind: http[s]://bucket.host[:port][/path];
     • urlpath — URL-path value. Accesses the bucket using a link of the following kind: http[s]://host[:port][/path]/bucket/.
     
     
   • s3_auto_region=<define the bucket region automatically> — checkbox Define the bucket region automatically. Select this checkbox if your provider supports automatic detection of the storage region. Uncheck the box to specify the value manually.
   • s3_region=<bucket region> — field Bucket region. Mandatory to be filled in. If the Define the bucket region automatically checkbox is selected, the value does not need to be specified.
   
   
8. Save the changes.

XML file

1. Go to the /usr/local/mgr5/etc/xml directory.
2. Create a file with a name of the following kind:  ispmgr_mod_<plugin name>.xml.
3. Edit the XML file according to the example:

   <?xml version="1.0" encoding="UTF-8"?>
   <mgrdata>
     <handler name="plugin.py" type="xml">
   	<event name="backup2.settings" before="yes"/>
   	<event name="backup2.settings" after="yes"/>
     </handler>
     <metadata name="backup2.settings" type="form" eqdist="1">
   	<form progress="yes">
     	<page name="banners">
       	<field name="token_new_info" noname="yes" fullwith="yes" base="yes">
         	<textdata type="banner" name="token_new_info" status="info"/>
       	</field>
     	</page>
     	<page name="storage">
       	<field name="storage_type" base="yes">
         	<select name="storage_type" setvalues="yes">
           	<if value="stype_new" hide="localstorage"/>
           	<if value="stype_new" hide="dropboxstorage"/>
           	<if value="stype_new" hide="yandexstorage"/>
           	<if value="stype_new" hide="ftpstorage"/>
           	<if value="stype_new" hide="warn_ftp_space_no_control"/>
           	<if value="stype_new" hide="sftpstorage"/>
           	<if value="stype_new" hide="googledrivestorage"/>
           	<if value="stype_new" hide="token_amazon"/>
           	<if value="stype_new" hide="token_dropbox_info"/>
           	<if value="stype_new" hide="token_googledrive_info"/>
           	<if value="stype_new" hide="token_amazon_info"/>
           	<if value="stype_local" hide="token_new_info"/>
           	<if value="stype_dropbox" hide="token_new_info"/>
           	<if value="stype_googledrive" hide="token_new_info"/>
           	<if value="stype_yandex" hide="token_new_info"/>
           	<if value="stype_amazon" hide="token_new_info"/>
           	<if value="stype_s3" hide="token_new_info"/>
           	<if value="stype_ftp" hide="token_new_info"/>
           	<if value="stype_sftp" hide="token_new_info"/>
         	</select>
       	</field>
     	</page>
   	</form>
     </metadata>
      <lang name="en">
   	<messages name="backup2.settings">
     	<msg name="stype_new">New storage</msg>
     	<msg name="token_new_info">To receive parameters for connecting to the storage follow the &lt;a href="__url__" target="_self"&gt;link&lt;/a&gt;. Necessary fields will be filled automatically.</msg>
   	</messages>
     </lang>
   </mgrdata>

4. Save the changes.

Replace the values with your own if necessary.

Handler file

1. Go to the /usr/local/mgr5/addon directory.
2. Create a handler file with the name that was specified in the XML file. The default name is plugin.py.
3. Edit the plugin file according to the example:

   #!/usr/bin/env python
   
   from sys import stdin
   import os
   import subprocess
   import xml.etree.ElementTree as etree
   
   def GetEndpoint():
   #Getting panel's ip address
     output = subprocess.check_output("/usr/local/mgr5/sbin/mgrctl -m ispmgr ihttpd out=xml", shell=True, encoding="utf8")
     ip = etree.fromstring(output).find(".//elem/port").text
     return "https://example.com/endpoint?ip=" + ip
   
   #Filling the form with values
   def Get(root):
   #Finding a selection form element
     select = root.find(".//slist[@name='storage_type']")
     if select is not None:
   #Adding an element
       elem = etree.Element("msg")
       elem.text = "stype_new"
   #Placing an element after the Local storage element
       select.insert(1, elem)
   #Generating a message with a link
       msg = root.find(".//messages/msg[@name='token_new_info']")
       if msg is not None:
         text = msg.text
         msg.text = text.replace("__url__", GetEndpoint())
   
   #Handling of clicking the “Save” button
   def Set(root):
   #Changing the parameter to make the setting work for S3 compatible storage
     param = root.find(".//storage_type")
     if param is not None and param.text == "stype_new":
       param.text = "stype_s3"
   
   if __name__ == "__main__":
   #Getting the value of the parameter passed by the panel from environment variables
     func = os.getenv('PARAM_func')
   #Checking if the right function is called
     if func == 'backup2.settings':
   #Reading xml passed from panel from stdin
       root = etree.parse(stdin).getroot()
   #Checking whether the handler is called before or after the action
       type = os.getenv("EVENT_TYPE")
   #Checking that the “Save” button is clicked
       if os.getenv('PARAM_sok') == 'ok' and type == 'before':
         Set(root)
       elif type == 'after':
         Get(root)
   #Writing the xml in stdout
       etree.dump(root)
     quit(0)

   Replace the link https://example.com/endpoint in the script with the address of your service that will send parameters for connecting to the S3 storage.

   Make sure that the values in the XML file match the values in the handler file. The stype_new and token_new_info parameter names must match for the XML file and the handler file. If the values have been changed, the names must be the same in both files.

   We recommend to use the provided handler file, though you can write your own similar handler file by changing its name in the contents of the XML file.

4. Save the changes.