ReadyNAS Applications Specification - ReadyNAS/sdk GitHub Wiki

ReadyNAS applications will be installed in the /apps folder. Each application is packaged as a Debian package that should be ready to install and remove. Each application is created in a separate sub-folder under the /apps folder. The application name is defined as the sub-folder. This name is presented as [AppName] in the rest of this document. [AppName] must begin with letter in lowercase or uppercase. [AppName] can contain numbers or minus -. The length of [AppName] must be greater than 5 and less than 25 characters. Lower case is preferred. [AppName] must match the Debian package name.

• Rule: [AppName] should be [a-zA-Z][-a-zA-Z0-9]{4,24}.

An application should limit all the application files other than pre-required system configuration files to /apps/[AppName] folder. If the application needs any file from the system folder, it should list the corresponding Debian packages for those files as dependencies. If your application needs its own startup file, the package must include systemd service file, and the service name MUST be fvapp-[AppName].service.


The application, at a minimum, should have the following basic folder structure.

/apps is a symlink to /{volume}/.apps/ (first data volume). This is the home of the entire application.

You MUST NOT create directories other than /apps/[AppName].


• /apps/[AppName]/
  • web/ [Folder for web resources]
  • config.xml [Configuration information]
  • https.conf [Optional]
  • http.conf [Optional]
  • fvapp-[AppName].service [Optional: If you have your own service]
  • logo.png [Required]

Hosting on our Apache server:

• https.conf: If you want to host your web content on our Apache server via HTTPS, this file needs to be included. A symbolic link to this file is included from /etc/frontview/apache/apps-https.conf.
  • Note: Your web content is needs to reside in the web/ folder.
• http.conf: If you want to host your web content on our Apache server via HTTP, this file needs to be included. A symbolic link to this file is included from /etc/apache2/sites-enabled/. You have the option to use the web/ folder or create your own folder for storing your web content.
• A sample of both https.conf and http.conf are provided.
• You can include either https.conf, http.conf, both, or none if you wish to host from your own web server.
• A symbolic link is created from /lib/system/system/ to fvapp-[AppName].service, if it exists.
• logo.png is required. Do not rename it. After installation, it will be accessible from https://[NAS]/apps/logo/[AppName].png. The logo will be presented in a 150px x 150px container, so it is recommended to create 150px x 150px PNG file.
  • Rule: logo.png must be 150px x 150px.

<Application resource-id="[AppName]">
	<Category>APP_CAT_NETWORK_MANAGE</Category>
	<Version>3.1.4-159265</Version>
	<MinFirmwareVer>6.0.5-T1271</MinFirmwareVer>
	<Name>My Application</Name>
	<Author>My Company</Author>
	<UnSupportedSystype>RN314,RN316,RN516</UnSupportedSystype>
	<ReservePort>7777</ReservePort>
	<ReservePort>7778</ReservePort>
	<ReservePort>5555</ReservePort>
	<LaunchURL>http://localhost:7777/index.php</LaunchURL>
	<ConfigURL>http://localhost:7778/index.html</ConfigURL>
	<InfoURL>http://www.readynas.com</InfoURL>
	<LogoURL>/apps/[AppName]/some/path/logo.png</LogoURL>
	<LicenseInfo>http://kb.netgear.com/app/answers/detail/a_id/2649/~/open-source-code-for-programmers-(gpl)</LicenseInfo>
	<DebianPackage>MyAppDebPackageName</DebianPackage>
	<ServiceName>fvapp-[AppName].service</ServiceName>
	<Description lang="en-us">This is my first app.</Description>
	<Description lang="ja-jp">最初のアプリ.</Description>
	<!-- You can add more languages if needed. -->
</Application>

[AppName] must begin with letter in either lowercase or uppercase. [AppName] can contain numbers or minus -. The length of [AppName] must be greater than 5 and less than 25 characters.

[AppName] is used to create a directory under /apps/. It is also used for the logo path, such as /apps/[AppName]/logo.png.

Rule: [AppName] is [a-zA-Z][-a-zA-Z]{4,24}

The version must match with the Debian package version. You should follow Debian policy. If you want to show version of dependencies, you can do so within your own config page (configured with the <ConfigURL> tag).

Specify the minimum firmware version that can run this application. For example, if you specify 6.0.5-T1271, then 6.0.5-T1234, 6.0.5-T1235, 6.0.6, 6.0.6-Txxxx, etc... can be used. Please note that 6.0.5 is newer than 6.0.5-Txxx.

It is also required to specify dependencies in Debian control file. The package name is readynasos and version number is 6.0.5~T1271 (Per Debian standard, all in lower case). Firmware versions prior to 6.0.5-T1271 do not have a readynasos Debian package installed.

For example, you can specify:

Depends: readynasos (>=6.0.5~T1271), php5-sqlite (>= 5.4.4-10)

A unique classification of your application. Required. Must match one of the categories below:

• APP_CAT_SECURITY_HOME
  • Security - Home: Protects your home
• APP_CAT_SECURITY_NETWORK
  • Security - Network: Protects your network
• APP_CAT_GAMING
  • Gaming: Have Fun in network
• APP_CAT_MEDIA
  • Media - Music/Video: Your media in your network
• APP_CAT_ENERGY
  • Energy - Home: Your Energy Management solution for the home
• APP_CAT_HOME_CONTROL
  • Home Control - Sensors: Control your home
• APP_CAT_STORAGE
  • Storage: Storage related apps
• APP_CAT_SUPPORT_TECH
  • Technical Support: Support related apps
• APP_CAT_NETWORK_MANAGE
  • Network Management - Configuration: Apps to configure your network
• APP_CAT_PRODUCTIVITY
  • Productivity: Apps to increase your productivity
• APP_CAT_BUSINESS
  • Business: Apps for business
• APP_CAT_OTHER
  • Other: Miscellaneous
• APP_CAT_HEALTH
  • Health: Health management solutions

Optional. The release notes for the current version.

Optional. Can specify multiple times. If app specifies a port number to be reserved for the app, NETGEAR will check conflicts with other apps and notify the developer if the desired port is available for use. Ports 1024-9999 can be used for <ReservePort>. Ports at or above 10000 can be used as a dynamically assigned port.

Optional. A URI to an external remote Smart Network Gadget UI application, or the entry point to the remote ui/gadget application. Can be ignored if remote ui/gadget entry point is index.html/index.html.

Optional. A URI to an external remote Smart Network Canvas (Full screen) UI application, or the entry point to the remote ui/application. Can be ignored if remote ui/app entry point is index.htm or index.html. If not specified, the corresponding UI components will be disabled or hidden.

This name is used in the NAS web interface. Any character can be used except &, <, >, \, or ". The length must be less than 48 characters (not 48 bytes). You can use unicode characters. NETGEAR may reject your app if an identical <Name> is already used.

Here is where you put your name or the name of your company.

Comma separated SYSTYPE. The app will not be available for download from Available Apps in the NAS web interface for these models. Current SYSTYPES as below.

If a URL is specified in this tag, the Launch button in the UI is enabled (the button is disabled otherwise). Clicking on the Launch button opens the URL in a new browser window. If specified as <LaunchURL/>, then the corresponding UI components will be disabled or hidden.

If a URL is specified in this tag, the Config button in the UI is enabled.

If a URL is specified in this tag, the information link shown in the web interface. For language selection, please refer tag.

This is used to run install/uninstall/update.

This is what the system uses to start/stop all your services. An example command would be systemctl start [AppName].service. If no service is required for this app (for example, if your app is an encyclopedia and consists of static pages only), then specify as <ServiceName/>. If no service is associated with the app, the ON/OFF switch in the web interface is disabled. We recommend the service to be a Type=notify. We recommend that you use the systemd-notify command or sd_notify() library call to notify when initialization is complete. The web interface will block operation until READY=1. Please refer to sample1 which uses the sd_notify() library call. When using the systemd-notify command, make sure that you set NotifyAccess=all in the unit definition file. Please consult the systemd man pages for further details.

This tag can define description of the application. The web interface may the limit number of lines depending on rendering scheme, so please keep this within a reasonable length. The following table shows the supported languages and language-codes:

readynasd is the daemon process which is responsible for changing system configurations and settings. Our main web interface talks with readynasd. We have opened some of this functionality to application developers. Currently the API is command line based, so if you want to call from your program, use system() or similar. Please check README.md, which is included in SDK for details and updated information.

• Call to start/stop the service

  Command	Description
  # /usr/bin/rn_nml –S [AppName]	Start [AppName] via systemd
  # /usr/bin/rn_nml –K [AppName]	Stop [AppName] via systemd

• Get share collection # /usr/bin/rn_nml –g shares

You can install your Debian package via the web interface. Under the Apps tab, there is an Upload button.

• Start/Stop button: We will handle this
• Launch button: This will launch the URL defined in <LaunchURL> in a separate browser window.
• Remove button: This will initiate the uninstallation process.
• Update button: This button appears only if an update is available.

• https.conf sample: (Access URL: https://[NAS]/apps/[AppName]/index.html)

  <Location /apps/sample1>
          Options Indexes FollowSymLinks
          AllowOverride None
          Order allow,deny
          allow from all
          Include "/etc/frontview/apache/Admin_Auth.conf"
          # You can use your own settings below.
  </Location>
  

• http.conf sample: (Access URL: http://192.168.1.3:7080/index.php)

  Listen 7080
  <VirtualHost *:7080>
          ServerAdmin admin@localhost
  
          DocumentRoot /apps/sample1/myfolder
          <Directory />
                  Options FollowSymLinks
                  AllowOverride None
          </Directory>
          <Directory /apps/sample1/myfolder />
                  Options Indexes FollowSymLinks MultiViews
                  AllowOverride None
                  Order allow,deny
                  allow from all
          </Directory>
  
          ErrorLog /apps/sample1/error.log
          LogLevel warn
  </VirtualHost>