Get SDK

MY CLOUD OS3 NAS

Introduction

Apps Package is a small package management system that designed for the My Cloud EX Series products. We refer to Add-ons in the document as Apps. As you can see by the below image, the UI refers to Add-ons as Apps. The SDK v2.0 provides basic functions to control packages. These controls are: install, remove, start, and stop. You only need to use the templates that are contained in the SDK, which are just simple shell scripts to create an App quickly and easily without writing complex programs.

Apps Package SDK v2.0

Apps Package SDK v2.0 includes the below three components:

    mksapkg: wrapping application into an App package

    document: this file

    sample: an easy sample that guides on how to create your own App

Getting Started: Using mksapkg

mksapkg is a small tool to help users create their own App for My Cloud NAS and it is based on Apps Package SDK v2.0. We provide the executable binary that users can use to create their own Apps on our system. Users must install libxml2 and GNU “tar” in their Linux system to run mksapkg**

Usage: mksapkg -E -s -m [module_name]

Missing xml2 library? For Fedora:

$ yum -y install libxml2 libxml2-devel

Write your own apkg.rc file

All string characters cannot contain spaces except the description field.

Package: utelnetd (the max length is 64)
Section: Apps
Version: 1.00 (the max length is 32)
Packager: WD (the max length is 32)
Email: support@wdc.com (the max length is 64)
Homepage: http://support.wdc.com (the max length is 64)
Description: This is a simple demonstration to wrapped telnet daemon. (the max length is 256)
AddonShowName: utelnetd (the max length is 64)
Icon: utelnetd.png
AddonIndexPage:
AddonUsedPort:
InstDepend:
InstConflict:
StartDepend:
StartConflict:
CenterType:
UserControl:
MinFWVer:
MaxFWVer:
IndividualFlag:

 

Here are the definitions of variables in apkg.rc:

 

About UserControl

UserControl is used to control the App visibility. Based on the parameter, the App could be visible on admin account only or both admin and user accounts.

If the UserControl value is “1”, only the admin can see the app.

Example:

Dropbox is set to “1”, and normal user can’t see the app.

Login by Admin:

Login by User:


About CenterType

If the CenterType value is “1”, and the setting page will build-in.

The CentherType value is “0”, and the setting page will pop-out.

Setting page build-in:


Setting page pop-out:


About MinFWVer & MaxFWVer

MinFWVerCurrent firmwareMaxFWVer

Format: 1.xx.xx.xx (support 6 token) 

If the MaxFWVer or MinFWVer is empty and it won’t check the min version or max version. The version limitation will check the current firmware version when installing apps.

Example:

MinFWVer: 1.03.00
MaxFWVer: 1.04.00

If the current firmware version is 1.02.00 or 1.05.00, App installation will return a failure.


About IndividualFlag


WebUI will show some notice information for Apps. If the App is completed by ALPHA, we will hide the information.

Example: 
Note: Support for each App should be obtained through the developer directly. The App's description in the WebUI shows support contact information.


About AddonIndexPage

If the “AddonIndexPage” is empty, the App will not provide a setting page.

The WebUI will still show the “configure” button, but it will not work.


Dependency & conflict rules defined by the App SDK v2.0:

 

Package:       A
…
InstDepend:    B
InstConflict:  C
StartDepend:   D
StartConflict: E, F

_   App A can't install when App B is not installed
_   App A can't install when App C is installed
_   App A can't enable when App D is not enabled
_   App A can't enable when App E or F is enabled


About Version

It must conform to the following format: xx.xx (ex: 1.2, 1.02, or 10.1, x is for numeric number only) 

When running mksapkg **, it will parse apkg.rc to create apkg.xml, and apkg.xml will be used by the App Server to get information about the installed App.

 

Sample:

<?xml version="1.0" encoding="UTF-8"?>
<config>
  <apkg>
    <item>
      <procudt_id>0</procudt_id>
      <custom_id>20</custom_id>
      <model_id>0</model_id>
      <user_control>0</user_control>
      <center_type>0</center_type>
      <name>utelnetd</name>
      <show>utelnetd</show>
      <enable>0</enable>
      <version>1.00</version>
      <date>20130301</date>
      <inst_date></inst_date>
      <path></path>
      <ps_name></ps_name>
      <url></url>
      <url_port></url_port>
      <apkg_version>WD</apkg_version>
      <packager>WD</packager>
      <email>support@wdc.com</email>
      <homepage>http://support.wdc.com</homepage>
      <inst_depend></inst_depend>
      <inst_conflict></inst_conflict>
      <start_depend></start_depend>
      <start_conflict></start_conflict>
      <description> This is a simple demonstration to wrapped telnet daemon.</description>
      <icon>utelnetd.png</icon>
      <MinFWVer></MinFWVer>
      <MaxFWVer></MaxFWVer>
    </item>
  </apkg>
</config>


Notes:

- The name of the directory where mksapkg is run from must match the app name. If not, app installation will fail.

- The app name is from “package name” in the apkg.rc file.

- Because mksapkg will compress the current directory when making the app, apkg will get app name which is from apkg.rc and use the name to check. If the app name doesn’t match with the directory name, app installation will fail.


Shell script files

preinst.sh: This script is used to pre-run some commands if needed, or for user to back up their configuration files to other places such as: /tamp, /var/tmp or any directory on your hard drive before installing an App.

install.sh: Will copy files and install App to an appropriate folder.

remove.sh: Will remove the installed App from hard drive.

init.sh: Will create necessary symbolic links of installed App before being executed (we suggest creating the symbolic link to /usr/bin or /usr/sbin). If necessary, restore the configuration files backed up through preinst.sh back to the App installation directory.

clean.sh: Will remove all links or files that created by init.sh.

start.sh: Will start App daemon.

stop.sh: Will stop App daemon.
 

Apps Package Naming Rules and Header Definition

APPS PACKAGE NAMING RULE

Ex: WDMyCloudEX4 utelnetd Package v1.00_03012013

 

APPS PACKAGE FILE BLOCKS

        apkg header       
      Module tar file     


Header structure definition

typedef struct _APKG_HEADER_
{
   char           ah_magic_num[MAGIC_NUM_LEN];
   char           ah_module_name[APKG_64_LEN];
   char           ah_version[APKG_32_LEN];
   int            ah_apkg_version;
   int            ah_product_id;
   int            ah_custom_id;
   int            ah_model_id;
   char           ah_reserve[64];
   unsigned long  ah_checksum;
   unsigned long  ah_length;
} APKG_HEADER, *APKG_HEADER_ID;

Header magic number definition: the last byte of magic number must be 0x5a in App SDK v2.0

WDMyCloudEX4: {0x4c,0x69,0x67,0x68,0x74,0x6e,0x69,0x5a}

WHEN WILL SHELL SCRIPT FILES BE CALLED?

When the Web UI uploads an App package, it is installed to:

Example : module name is (MNAME) = utelnetd
default install path: (INST_PATH) = /mnt/HD/HD_a2/Nas_Prog/$MNAME
default upload path: (UPLOAD_PATH) = /mnt/HD/HD_a2/Nas_Prog/_install

The install and upload path is scanned dynamically by the App server when daemon is initiated.

 

When installing a new App, the following shell script will be called:

$UPLOAD_PATH/install.sh $UPLOAD_PATH $INST_PATH
$INST_PATH/init.sh $INST_PATH

 

When removing an App, the following shell script will be called:

$INST_PATH/stop.sh
$INST_PATH/clean.sh
$INST_PATH/remove.sh $INST_PATH

 

When enabling an App, the following shell script will be called:

$INST_PATH/start.sh

 

When disabling an App, the following shell script will be called:

$INST_PATH/stop.sh

 

When re-installing an App, the following shell script will be called:

$INST_PATH/stop.sh
$INST_PATH/clean.sh
$INST_PATH/preinst.sh $INST_PATH
$INST_PATH/remove.sh $INST_PATH
$UPLOAD_PATH/install.sh $UPLOAD_PATH $INST_PATH
$INST_PATH/init.sh $INST_PATH

When your app has its own configure file settings, you need to backup these files to other place in preinst.sh script file and copy files back in init.sh. Because remove.sh will remove all configuration files of this App on the hard disk and reinstall it in install.sh. Beware of incorrect shell script files which may cause the system to crash. For example, without the remove link from hard drive correctly, it may cause the system to format hard drive failure due to hard drive can't be un-mounted.

App Server

  • The App Server will scan all volume to find out the installed Apps and enable it, if necessary
  • The App Server will control and maintain installed database of Apps
  • Apps Server will provide interface to run shell script file from Web GUI

The main purpose of Apps SDK v2.0 is implemented the App dependencies and configuration check.

Sample App Package Without a Web UI

Prepare the necessary binaries of your application, and create a folder name that is the same name as the Package field in the apkg.rc file.

$ ls -R
.:
apkg.rc  bin  clean.sh  init.sh  install.sh  preinst.sh  remove.sh  start.sh  stop.sh

./bin:
utelnetd

 

Create your own apkg.rc file

Package:            utelnetd
Version:            1.00
Packager:           WD
Email:              support@wdc.com
Homepage:           http:// support.wdc.com
Description:        This is a simple demonstration to wrapped telnet daemon.
Icon:               utelnetd.png
AddonShowName:      utelnetd
AddonIndexPage:
AddonUsedPort: 
InstDepend:
InstConflict: 
StartDepend: 
StartConflict:
CenterType:
UserControl:
MinFWVer:
MaxFWVer:

 

Write preinst.sh

#!/bin/sh

path_src=$1
path_des=$2
#we do nothing here for utelnetd

 

Write install.sh (most apps will use this example)

#!/bin/sh

path_src=$1
path_des=$2
mv $path_src $path_des

 

Write remove.sh (most apps will use this example)

#!/bin/sh

path=$1
rm -f /usr/bin/utelnetd 2> /dev/null
rm -f /var/www/utelnetd >/dev/null
rm -rf $path

 

Write init.sh

#!/bin/sh

path=$1

#create link
ln -s $path/sbin/utelnetd /usr/bin/utelnetd
ln -s $path/var/www/utelnetd /var/www

#cmd on pre-install
idx=0
while [ $idx -lt 7 ]; do
     mknod /dev/ptyp$idx c 2 $idx 2>/dev/null
     mknod /dev/ttyp$idx c 3 $idx 2>/dev/null
     idx=`expr $idx + 1`
done

 

Write clean.sh

#!/bin/sh

#remove link
rm -f /usr/bin/utelnetd  2> /dev/null
rm -f /var/www/utelnetd >/dev/null
rm -f /dev/ttyp*
rm -f /dev/ptyp*

 

Write start.sh

#!/bin/sh

#start daemon
utelnetd -d

 

Write stop.sh

#!/bin/sh

#stop daemon
killall utelnetd

 

Create Apps package using mksapkg

[hostname ~ /mksapkg/utelnetd]$ ls
apkg.rc  bin  clean.sh  init.sh  install.sh  preinst.sh  remove.sh  start.sh  stop.sh
[hostname ~ /mksapkg/utelnetd]$ mksapkg -E -s -m WDMyCloudEX4
============================================
        mksapkg version: v1.1
============================================
utelnetd/
utelnetd/remove.sh
utelnetd/apkg.rc
utelnetd/clean.sh
utelnetd/apkg.sign
utelnetd/bin/
utelnetd/bin/utelnetd
utelnetd/utelnetd.png
utelnetd/init.sh
utelnetd/apkg.xml
utelnetd/install.sh
utelnetd/stop.sh
utelnetd/start.sh
utelnetd/preinst.sh
***[../WDMyCloudEX4_utelnetd_1.00.bin(06192013)]

NAS type:               WDMyCloudEX4
module name:            utelnetd
module versioin:        1.00
packager:               WD

header length:          26659
header checksum:        E40297BE

Add-ons "../WDMyCloudEX4_utelnetd_1.00.bin(06192013)" create!

 

What happens when the installed App doesn’t work?

If an App is not installed correctly, then the package will not install, remove, enable, or disable due to improper shell script files creation. It is easy to solve this error by removing the installed package folder and sending a rescan command to the APKG daemon.

# rm -rf /mnt/HD/HD_a2/Nas_Prog/utelnetd
# kill -USR1 `pidof apkg`

When you are at the stage of development, it is recommended not to install other Apps. This is because a clean environment will help you to reduce development time for debugging.

Create web page

Check these items in the apkg.rc file:

Package:            hello
...
Icon:               hello.png
AddonShowName:      hello
AddonIndexPage:     index.html
AddonUsedPort:      
…

Note: If your package does not require a GUI, make sure the AddonIndexPage field is empty.

In the Application page, we need to have an App icon and the recommended icon size is 128xn or nx128 (n > 128).

Icon naming rules: Package_name.png.

When package name is hello, you should rename icon file as hello.png. And make sure the icon can be found in the /var/www/hello/hello.png. 
Put your html, jpg, css files in the webpage directory. You should link webpage to /var/www/hello, because the root path of web server is /var/www. 
When you implement cgi functions, you should link to /var/www/cgi-bin. Just write it down on init.sh script file. And remember to add remove link command on clean.sh script file.

ln -s $path/webpage /var/www/hello
ln -s $path/cgi/* /var/www/cgi-bin/

Make sure the path of index file is correct. ex:

AddonIndexPage:     index.html  -> you should have this file in /var/www/hello/index.html
AddonIndexPage:     /web/index.html -> you should have this file in /var/www/hello/web/index.html

Multi-language Support

We support multiple languages in the app’s description. Please put language xml file to Addon_Name/web/desc.xml and link the language file to /var/www/Addon_Name in init.sh when creating the addon package.

1. Put language xml file to the add-on folder. 


2. Add link command for the desc.xml file to init.sh

WEBPATH="/var/www/aMule/"
Path=” /mnt/HD/HD_a2/Nas_Prog/aMule”

ln -s $path/web/desc.xml  $WEBPATH


You can put “desc.xml” to anywhere in add-on package, but you must link the page to its folder.

The Web UI will check the “desc.xml” file to show the indicated language.


The desc.xml example for Icecast:

<?xml version="1.0" encoding="utf-8"?>
<config>
  <en-US>A free server software for streaming multimedia.</en-US>
  <cs-CZ>Bezplatný serverový software pro vysílání multimediálního obsahu.</cs-CZ>
  <de-DE>Eine kostenlose Serversoftware für das Streaming von Multimedia-Inhalten.</de-DE>
  <es-ES>Software gratuito de servidor para transmitir contenido multimedia.</es-ES>
  <fr-FR>logiciel serveur gratuit de diffusion de contenus multimédias.</fr-FR>
  <hu-HU>Ingyenes kiszolgálószoftver a multimédiás tartalmak adatfolyam útján történ_ továbbításához.</hu-HU>
  <it-IT>software server gratuito per lo streaming dei contenuti multimediali.</it-IT>
  <ja-JP>マルチメディア ストリーミング用の無料サーバー ソフトウェア。</ja-JP>
  <ko-KR>멀티미디어 스트리밍을 위한 무료 서버 소프트웨어.</ko-KR>
  <no-NO>Et gratis serverprogram for direkteavspilling av multimedia.</no-NO>
  <nl-NL>Een gratis serversoftware voor het streamen van multimedia.</nl-NL>
  <pl-PL>Bezp_atne oprogramowanie serwerowe do strumieniowych transmisji danych multimedialnych.</pl-PL>
  <pt-BR>Um software de servidor gratuito para fazer transmissão multimídia.</pt-BR>
  <ru-RU>Бесплатное серверное программное обеспечение для потокового воспроизведения мультимедиа.</ru-RU>
  <sv-SE>En gratis serverprogramvara för strömning av multimedia.</sv-SE>
  <tr-TR>Multimedya akı_ına yönelik ücretsiz bir yazılım.</tr-TR>
  <zh-CN>用于流式传输多媒体的免费服务器软件。</zh-CN>
  <zh-TW>用於串流多媒體的免費伺服器軟體。</zh-TW>
</config>

Update Apps

If the installed app has a new update available from the server, the system will automatically prompt the user that an update is available to download. The user can then click on the notice to check for apps with available updates.

 

Apkg wil remove the old app, then install the new app.

The "preinst.sh" script will back up the app's configuration, then "install.sh" will recover the configuration.

Re-install flow:

stop.sh -> clean.sh -> preinst.sh -> remove.sh -> install.sh -> init.sh

 

Example: preinst.sh

#!/bin/sh
path_des=$1

cp -R $path_des/iceconf /mnt/HD/HD_a2/.systemfile/

 

Example: install.sh

#!/bin/sh
path_src=$1
path_des=$2

echo "Addon Icecast (install.sh): installing ..."
mv $path_src $path_des

if [ -d /mnt/HD/HD_a2/.systemfile/iceconf ]; then
        echo "Addon Icecast (install.sh): restore configs ..."
        cp -R /mnt/HD/HD_a2/.systemfile/iceconf "${path_des}/Icecast/"
        rm -rf /mnt/HD/HD_a2/.systemfile/iceconf
fi
echo "Addon Icecast (install.sh): Done ..."

Support Project

Usage: mksapkg -E -s -m [module_name]
Module name Project name
WDMyCloudEX4 LIGHTNING-4A
WDMyCloudEX2 KingsCanyon
WDMyCloud Glacier
WDMyCloudEX4100 YellowStone
WDMyCloudDL4100 Sprite
WDMyCloudEX2100 Yosemite
WDMyCloudDL2100 Aurora
WDMyCloudMirror Zion
WDMyCloudMirrorGen2 GrandTeton
MyCloudEX2Ultra RangerPeak
MyCloudPR4100 BlackCanyon
MyCloudPR2100 BryceCanyon

Downloads

Click here to visit the My Cloud OS3 NAS Downloads page  **

** Requires a free Developer Portal account - click here to register

Do more with the
My Cloud OS3 NAS SDK

Click the buttons below to visit the My Cloud OS3 NAS Developer Home & Workflow pages

 

Developer
Home

Get started, access the SDK, build your apps, & learn more


View Home

Developer
Workflow

Register & submit your app for review and contact support


View Workflow