AXP(Application eXtension Platform)/helloworld

バージョン 5

    AXP(Application eXtension Platform)へ戻る

     

     

    ここでは、Cisco Application eXtension Platform Developer ガイド の Hello World アプリケーションの作成手順について説明します。

    この章では、AXPアプリケーションの基本的な作成方法を学ぶことができます。

     

    準備

    開発システムの準備 が整っていることを確認してください。

    • ※ ここでは、AXP SDKのインストールパスを、/opt/AXP/sdk としています。

     

    同梱のサンプルについて

    1.5 より、SDKにHelloWorld サンプルが同梱されています。/opt/AXP/sdk/examples/HelloWorld を参照してください。 詳細については、同フォルダのREADMEに記載がありますが、ここでは簡単に説明をします。

     

    1. examples/HelloWorld に移動します。
    2. PackagingParameters.txt を編集し、auth-bundle と private-key の設定をします。
    3. ../../tools/pkg_build.sh --file PackagingParameters.txt を実行します。パッケージの作成が成功すると、以下のような表示が出力されます。          
      ~省略~
      Generated shutdown timeout option: 30
      Creating project directories...
      Generated Application UUID: 049d6133-15fb-4196-9c97-ad9a6b0257a0
      Preparing configuration for the core packaging tool...
      Creating runtime signatures...
      ~省略~
      Renaming HelloWorld.pkg -> HelloWorld.1.0.pkg

      Generated files:
        Output package: /opt/AXP/sdk/examples/HelloWorld/package/pkg/HelloWorld.1.0.pkg
        Output payload: /opt/AXP/sdk/examples/HelloWorld/package/pkg/HelloWorld.1.0.prt1
      ※ここで生成されたUUIDをメモしてください。
    4. 作成された、HelloWorld.1.0.pkg および prt1 を FTPサーバのパスへコピーします。
    5. [HelloWorld] $ cp package/pkg/HelloWorld.1.0.* /var/ftp
    6. AXPにパッケージをインストールします。
      AXP# software install package url ftp:///HelloWorld.1.0.pkg
      パッケージのインストールが成功すると、再起動します。
    7. パッケージがインストールされているか確認します。    

      AXP#  show software packages

      ~省略~

      - HelloWorld (This is my HelloWorld program on AXP!) (1.0)

    8. アプリケーションコンソールに接続し、fancy_outputを確認します。   
      AXP# app-service HelloWorld
      AXP(exec-HelloWorld)# connect console
      console-3.2# cat /fancy_output
      Hello world!
      Hello world!
      Hello world!
      console-3.2#

     

    ここからの説明は、すべて手作業でアプリケーションを作成した場合になります。基本的な作成方法について記載されていますので、参照してください。

    作業フォルダの作成

    ※  ガイドでは、作業フォルダが、/source/helloworldapp となっていますが、ここでは、/opt/AXP/apps/helloworld で作業を行います。

     

    作業フォルダを作成します。

    [~]# cd /opt/AXP/apps
    [apps]# mkdir helloworld
    [apps]# cd helloworld
    [helloworld]# mkdir -p build/bin
    [helloworld]# mkdir -p build/etc/rc.d/init.d
    [helloworld]# mkdir -p build/etc/rc.d/rc3.d
    [helloworld]# mkdir -p build/etc/rc.d/rc6.d
    [helloworld]# mkdir -p build/opt
    [helloworld]# mkdir -p build/var/log
    [helloworld]# mkdir -p package

     

    buildフォルダは、AXPに展開されるイメージです。実際に、AXPにインストールが行われると、次のディレクトリが作成されることになります。ルートに展開されるtarボールとして理解するとわかりやすいと思います。

    /bin
    /etc/rc.d
            init.d
            rc3.d
            rc6.d
    /opt
    /var/log

     

    packageフォルダは、パッケージ作成ツールで使用するフォルダになります。AXPにインストールするためのパッケージが作成されます。

     

    アプリケーションの記述

    実際に実行するアプリケーションを記述します。

    ここで作成するアプリケーションは、/var/log/fancy_output に Hello Worldという文字列を記録するプログラムです。

    1. helloworld.shを作成します。
      [helloworld]# cd build/opt
      [opt]# vi helloworld.sh
    2. 以下のように編集します。
      1. #!/bin/bash
      2.
      3. #provide health status
      4. /bin/app_status_notifier helloworld INITIALIZING
      5.
      6. # remove old log file
      7. rm -rf /var/log/fancy_output.log
      8.
      9. #provide health status
      10. /bin/app_status_notifier helloworld ALIVE
      11. echo "`date` Hello world begin" >> /var/log/fancy_output.log
      12. CNT=0
      13. while [ $CNT -lt 60 ]; do
      14.  echo "`date` Hello world" >> /var/log/fancy_output.log
      15.  sleep 10
      16.  let CNT=CNT+1
      17. done
      18. echo "`date` Hello world end" >> /var/log/fancy_output.log
      19.
      20. /bin/app_status_notifier helloworld DOWN
      4,10,20行は、AXPにアプリケーションのステータスを通知するためのコマンドです。app_status_notifier は build フォルダに存在しませんが、ゲストOSをAXPが生成する際に作成します。
      11-18行は、日付とHello World をfancy_outputファイルに記録するプログラムです。
      ※ ガイドでは,HelloWorldが無限ループになっていますが、このサンプルは10秒毎に60回(10分実行)するようにしています。
    3. helloworld.shに実行属性をつけます。
      [opt]# chmod +x helloworld.sh

     

    自動起動の設定

    自動起動を設定するため起動スクリプトを作成します。

    1. init.d に起動スクリプトを作成します。
      [helloworld]# vi build/etc/rc.d/init.d/helloworld


      #!/bin/sh

      . /etc/rc.d/init.d/functions

      exec=/opt/helloworld.sh
      prog=$(basename $exec)

      [ -f $exec ] || exit 0

      start() {
              echo -n $"Starting $prog: "
              $exec &
              echo
      }

      stop() {
              echo -n $"Stopping $prog: "
              killproc $prog
              echo
      }

      restart() {
              stop
              start
      }

      case "$1" in
          start|stop|restart)
              $1
              ;;
          *)
              echo $"Usage: $0 {start|stop|restart}"
              exit 2
      esac
    2. ブート時の起動設定と、
      [helloworld]# cd build/etc/rc.d/rc3.d
      [rc3.d]# ln ../init.d/helloworld S99helloworld
      [rc3.d]# cd ../rc6.d
      [rc6.d]# ln ../init.d/helloworld K99helloworld
      ※ ソフトリンクは、相対アドレスで指定してください。buildフォルダを含めた絶対アドレスで指定することはできません。

     

    コンソールアクセスのための設定

    AXPのCLIから、アプリケーションのゲストOSシェルへアクセスできる設定を行います。

    これらの設定を行うことで、コマンドconnect consoleより、アプリケーションからゲスト OS シェルにコンソールアクセスができるようになります。

    1. post-install.shを作成します。
      [helloworld]# vi build/bin/post-install.sh


      #!/bin/bash
      ln -s /bin/login.sh /bin/console
    2. login.shを作成します。
      [helloworld]# vi build/bin/login.sh


      #!/bin/bash
      bash -login
    3. 実行属性を与えます。
      [helloworld]# chmod +x build/bin/*.sh

     

    パッケージの作成

    1. アプリケーションの UID(固有識別情報)を作成することで、AXPでの管理が容易になります。
      [helloworld]# uuidgen
      0e9114b7-1c97-4edd-aaac-94363fdeeea8
    2. パッケージを作成します。(※/opt/AXP/axp-sdk.1.5.3/tools にパスが通っているか確認してください。)
      [helloworld]# pkg_build.sh
      SLIM Packaging Utility. (C) 2007-2009 Cisco Systems, Inc
      Checking dependencies...

      WARNING: If an application from AXP 1.0/1.1 is repackaged to be installed
              on AXP 1.5, please make sure to increment the application version

      No command parameters specified - entering interactive mode.

      ** project-dir
      Project directory will be used to store output packages as well as
      any intermediary files, for example manifest files. Project directory
      must be readable and writable

      Project Directory: /opt/AXP/apps/helloworld/package

      ** auth-bundle
      Authorization bundle provided by Cisco Systems. This bundle is
      required to allow your application to install and run on
      the target blade

      Authorization Bundle: /opt/AXP/keys/auth_bundle.sig

      ** private-key
      Private key stored in this file will be used to sign application
      package files. Public key corresponding to this private key must
      be stored in development certificate

      Private Key for Signing Operations: /opt/AXP/keys/private.key

      ** name
      Name of application to be packaged. This name will be used to identify
      application through command line interface as well as for naming
      package files

      Application Name: helloworld

      ** version
      Application version is used when displaying application information
      through command line interface. It is also used for upgrade/downgrade
      sequencing

      Version: 1.0

      ** description (optional)
      Application description is used when displaying application information
      through command line interface. For example it may contain a statement
      about application's capabilities

      Description: helloworld sample app

      ** uuid (optional)
      Unique identifier to be used with this application. The identifier can
      be generated using Linux 'uuidgen' utility. It will be automatically
      generated if left blank

      Unique Identifier: 0e9114b7-1c97-4edd-aaac-94363fdeeea8

      ** source-dir
      Source directory contains the files to be packaged. Files must be laid
      out in the same manner as they will appear on the root file system when
      installed in the application hosting environment

      Source Directory: /opt/AXP/apps/helloworld/build

      ** protect (optional)
      File that contains a list of application files to be protected. All
      files listed in this file will be verified during system startup.
      No application files will be protected if this parameter is left blank

      Protect List File:

      ** deps (optional)
      Application may depend on one or more components outside of its own
      package. Dependencies are specified based on application's unique
      identifiers. This tool can lookup application unique identifiers
      for packages in '/pkg' and '/pkg' directories.
      If this option is not specified the application will have no
      dependencies

      Loading existing SLIM Packages in directories:
        /opt/AXP/axp-sdk/pkg
        /opt/AXP/apps/helloworld/package/pkg

      AXP add-ons
      UUID                                    NAME            Disk    CPU    Memory  Description
      b4b0ee92-cf8e-472b-8434-e8e7412ec71a    cli_plugin      0      10      5      CLI Plugin
      8cec8ee5-54c3-4667-b62e-d4a31805d44a    iosapi          0      10      5      IOS CLI API
      545c3671-c4bc-43b8-bce4-690123ab9d4d    eventapi        0      10      5      IOS Event API
      7a013f0e-07cb-4c25-8122-4a0af7704c3b    vserialapi      0      10      5      Remote Serial Device support
      5d9267f0-f9c2-11db-8f0d-001635a94464    app_dev        0      10      5      Application Debugging Add-on Package
      Dependency Subsystem Identifier:

      ** disk-limit
      disk limit option specifies the minimum disk space allocated
      for the application. When disk resource falls below this limit, the
      application will not be allowed to install. Minimum disk limit must be
      specified in megabytes, for example 1500M.

      Disk Limit: 300M

      ** memory-limit
      Memory limit option allocates RAM space for the application.
      Memory limit must be specified in megabytes, for example 256M

      Memory Limit: 128M

      ** cpu-limit
      CPU limit option specifies the minimum amount of cpu resource
      allocated for the application. When the cpu resource falls below this
      limit, the application will not be allowed to install.
      This option is uniform across supported platforms so the same package
      can be installed on any of the supported platforms of the same CPU
      architecture. Please refer to developer's guide for the information on
      how to calculate CPU limit

      Cpu Limit: 200

      ** swap (optional)
      swap option specifies whether swap needs to be turned on or off on the
      Network Module. The application can specify ON or OFF; the system will
      enable/disable swap after reboot based on Application's requirement.
      Please note that swap option specified for an application's addon will be ignored

      Swap Space:

      ** postinstall (optional)
      Postinstall script is executed after installation is complete but before
      the application has been started for the first time. Postinstall script
      must be packaged with the application. When entering postinstall script
      location, use relative path with respect to source tree directory

      Post-install script path: bin/post-install.sh

      ** preupgrade (optional)
      Preupgrade script is executed before the upgrade takes place.
      Preupgrade script is first extracted from the incoming package
      it is then executed in vserver. When entering preupgrade script
      location, use relative path with respect to source tree directory

      Pre-upgrade script path:

      ** preupgrade-oldver (optional)
      Preupgrade_oldver script is executed before the upgrade takes place.
      Preupgrade_oldver script is found and executed from the currently installed
      version of the application. When entering preupgrade-oldver script
      location, use relative path with respect to source tree directory

      Pre-upgrade-oldver script path:

      ** cap-config (optional)
      Capabilities configuration file can be used to relax certain restrictions
      in the virtual container. Only the capabilities granted by the development
      authorization file can be configured

      Capabilities Configuration File:

      ** share-timezones (optional)
      Specify whether this application will share the system's timezone
      information. If enabled, the application will be given timezone
      information from the system at the time the application starts.
      If disabled, the application will use it's own timezone information.
      This can be ON(default) or OFF.

      Share Timezone Option:

      ** shutdown-timeout (optional)
      Specify the shutdown timeout value for the application.  This is specified
      in seconds and can vary from 0-300.  The default value is 30.

      Shutdown Timeout Option:

      ** disk-wildcard (optional)
      Specify if the disk-wildcard feature is enabled or disabled(default.)
      If enabled, the application is permitted to exceed its disk limit.
      When a new package is installed, the remaining free disk space is
      divided evenly amongst applications with the disk-wilcard feature
      enabled.

      Enable disk wildcard support? (y/n): n
      ** memory-wildcard (optional)
      Specify if the memory-wildcard feature is enabled or disabled(default.)
      If enabled, the application is permitted to exceed its memory limit.
      When a new package is installed, the available memory is divided evenly
      amongst applications with the memory-wildcard feature enabled.

      Enable memory wildcard support? (y/n): n
      ** cpu-wildcard (optional)
      Specify if the cpu-wildcard feature is enabled or disabled(default.)
      If enabled, the application is permitted to exceed its cpu limit.
      When a new package is installed, the available CPU is divided evenly
      amongst applications with the cpu-wildcard feature enabled.

      Enable cpu wildcard support? (y/n): n
      ** user-defined-linux (optional)
      Select yes to use the User Defined Linux Environment.
      Select no (default) to use the AXP Reference OS Environment.

      Use User Defined Linux Environment? (y/n): n
      Interactive mode complete. Resulting CLI command:

      -------------------
      /opt/AXP/axp-sdk/tools/pkg_build.sh --project-dir '/opt/AXP/apps/helloworld/package' --auth-bundle '/opt/AXP/keys/auth_bundle.sig' --private-key '/opt/AXP/keys/private.key' --name 'helloworld' --version '1.0' --description 'helloworld sample app' --uuid '0e9114b7-1c97-4edd-aaac-94363fdeeea8' --source-dir '/opt/AXP/apps/helloworld/build' --disk-limit '300M' --memory-limit '128M' --cpu-limit '200' --postinstall 'bin/post-install.sh'
      -------------------

      Press enter to continue...

      ~略~
      Generating files:
        Output packages: /opt/AXP/apps/helloworld/package/pkg/helloworld.1.0.pkg
        Output payload:  /opt/AXP/apps/helloworld/package/pkg/helloworld.1.0.prt1
        Text config file: /opt/AXP/apps/helloworld/package/pkg/helloworld.1.0.20091225.cfg
      • ※ ここで表示されたCLIは、対話方式を使わずに使用することができます。
      • ※ 途中、パッケージングプロセスが停止した場合は、 /opt/AXP/apps/helloworld/package/tmp/core.log を確認してください。
    3. 作成したパッケージをftpフォルダにコピーします。
      [helloworld]# cp package/pkg/helloworld* /var/ftp

     

    AXPへインストール

    1. SSH(またはtelnet)でAXPにログインします。
    2. パッケージをインストールします。
      AXP> software install add url ftp://192.168.1.36/helloworld.1.0.pkg

      Downloading ftp helloworld.1.0.pkg
      Bytes downloaded :  8124

      Validating package signature ...
      ~略~
      exec_script python /lib/python2.3/installer/install_dynamic_policy.py / helloworld
      Installing dynamic policy. Return code is success.
      INIT:
      Rebooting ...
    3. AXPが再起動します。
    4. 起動が完了したら、パッケージがインストールされたか確認します。
      AXP> show software packages

      Installed Packages:
      ~略~
      Installed Plug-ins:
      - helloworld (Hello there!) (1.0)
      ~略~
    5. 正常に実行されている場合は、show app-service state で ALIVEになります。
      AXP> show app-service state
                        APPLICATION                STATE              HEALTH
                          helloworld              online                ALIVE
    6. 出力されたfancy_logを確認します。
      AXP> app-service helloworld
      AXP(exec-helloworld)> show log name fancy_output.log
      Thu Mar 19 13:20:14 JST 2009 Hello world begin
      Thu Mar 19 13:20:14 JST 2009 Hello world
      Thu Mar 19 13:20:19 JST 2009 Hello world
      Thu Mar 19 13:20:24 JST 2009 Hello world
      Thu Mar 19 13:20:29 JST 2009 Hello world
      ※ show log は、ゲストOSの/var/logフォルダ内にあるファイルを表示することができます。また、show logs コマンドでファイルリストを得ることができます。
    7. しばらくしたら、helloworldが終了したことを確認します。
      AXP> show app-service state
                        APPLICATION                STATE              HEALTH
                          helloworld              online                DOWN
      AXP> app-service helloworld
      AXP(exec-helloworld)> show log name fancy_output.log
      ~略~
      Thu Mar 19 18:24:22 JST 2009 Hello world
      Thu Mar 19 18:24:32 JST 2009 Hello world
      Thu Mar 19 18:24:42 JST 2009 Hello world
      Thu Mar 19 18:24:52 JST 2009 Hello world end
      AXP>

     

    アプリケーションのステータス管理

    アプリケーションは、Cisco AXP アプリケーションモニタリング機能を使用する、1 つまたは複数のウォッチドッグスクリプトまたは実行可能ファイルをパッケージにバンドルして提供する必要があります。

    1. ウォッチドッグスクリプトは、前もって定義されているディレクトリ/opt/app_status_monitor/watchdogs/ に配置する必要があります。
      [~]# cd /opt/AXP/apps/helloworld/
      [helloworld]# mkdir -p build/opt/app_status_monitor/watchdogs
    2. ウォッチドックスクリプトを作成します。
      [helloworld]# vi build/opt/app_status_monitor/watchdogs/W01helloworld.sh


      #!/bin/bash
      APP=helloworld.sh
      APPNAME_NO_EXT=helloworld
      PID_FILE=/var/run/${APPNAME_NO_EXT}.pid
      if [ ! -e $PID_FILE ]; then
        exit 1;
      fi
      PID_FROM_FILE=`cat ${PID_FILE}`
      for x in `ps -ef|grep $APP |awk '{print $2}'`
      do
        if [ $x == "${PID_FROM_FILE}" ]; then
          exit 0
        else
          exit 1
        fi
      done
    3. ウォッチドックスクリプトに実行属性をつけます。
      [helloworld]# chmod +x build/opt/app_status_monitor/watchdogs/W01helloworld.sh
    4. ウォッチドックスクリプトが、監視するpidファイルを作成するように helloworld.shを修正します。
      [helloworld]# vi build/opt/helloworld.sh


      1. #!/bin/bash
      2.
      3. #provide health status
      4. /bin/app_status_notifier helloworld INITIALIZING
      5.
      6. #create helloworld.pid file
      7. PID_FILE=/var/run/helloworld.pid
      8. ps -ef|grep helloworld.sh|grep -v grep|awk '{print $2}' > $PID_FILE
      9.
      10. # remove old log file
      11. rm -rf /var/log/fancy_output
      12.
      13. #provide health status
      14. /bin/app_status_notifier helloworld ALIVE
      15. echo "`date` Hello world begin" >> /var/log/fancy_output
      16. CNT=0
      17. while [ $CNT -lt 60 ]; do
      18.  echo "`date` Hello world" >> /var/log/fancy_output
      19.  sleep 10
      20.  let CNT=CNT+1
      21. done
      22. echo "`date` Hello world end" >> /var/log/fancy_output
      23.
      24. /bin/app_status_notifier helloworld DOWN
      25.
      26. rm $PID_FILE
      6-8行でpidファイルを作成し、26行でpidファイルを削除します。

     

    パッケージの更新

    ウォッチドックスクリプト版をインストールするために、パッケージの更新を行います。

    1. バージョンを変更し、パッケージを作成します。
      pkg_build.sh で生成されたCLIを編集して実行します。
      変更する箇所は、--version を 1.0.1 にします。
      [helloworld]# pkg_build.sh \
        --project-dir '/opt/AXP/apps/helloworld/package' \
        --auth-bundle '/opt/AXP/keys/auth_bundle.sig' \
        --private-key '/opt/AXP/keys/private.key' \
        --name 'helloworld' --version '1.0.1' --description 'helloworld sample app' \
        --uuid '0e9114b7-1c97-4edd-aaac-94363fdeeea8' \
        --source-dir '/opt/AXP/apps/helloworld/build' \
        --disk-limit '300M' --memory-limit '128M' --cpu-limit '200' \
        --postinstall 'bin/post-install.sh'
      または、コンフィグレーションファイルを作成することで、パッケージ作成を容易に行うことができます。
      [helloworld]# vi config.txt
      project-dir=./package
      auth-bundle=/opt/AXP/keys/auth_bundle.sig
      private-key=/opt/AXP/keys/private.key
      name=helloworld
      version=1.0.1
      description=helloworld sample app
      uuid=0e9114b7-1c97-4edd-aaac-94363fdeeea8
      source-dir=./build
      disk-limit=300M
      memory-limit=128M
      cpu-limit=200
      postinstal=bin/post-install.sh
      [helloworld]# pkg_build.sh --file config.txt
    2. パッケージをftpフォルダへコピーします。
      [helloworld]# cp package/pkg/helloworld* /var/ftp
    3. AXPでパッケージをアップグレードします。
      AXP# software install upgrade url ftp://192.168.1.36/helloworld.1.0.1.pkg
      NOTE:software download server url コンフィグを行うことで、ftpのURLを省略することができます。 
      AXP# conf t
      AXP(config)# software download server url ftp://192.168.1.36
      AXP(config)# exit
      AXP# wr
      AXP# software install upgrade helloworld.1.0.1.pkg
    4. AXPが再起動します。
    5. パッケージが正しくアップグレードしたか確認します。
      AXP> show software packages
      ~略~
      - helloworld (Hello there!) (1.0.1)
      ~略~
      AXP> show app-service state
                        APPLICATION                STATE              HEALTH
                        helloworld              online                ALIVE

     

    ステータスモニタ

    ウォッチドックを設定すると、ステータスモニタを確認することができます。

    1. ステータスモニタを確認します
      AXP> app-service helloworld

      AXP(exec-helloworld)> show status-monitor
      Application:                  helloworld
      Monitor status:                PASSED
      Monitor in progress:          No
      Last executed watchdog:        W01helloworld.sh
      Last executed date:            Thu Mar 19 19:30:59 JST 2009
      Last failed watchdog:          ---
      Last failed return code:      -
      Last failed date:              ---
      Last restarted date:          ---
      Recovery threshold:            5
      Monitor interval:              12
    2. ステータスモニタが正常に動作していない場合は、以下の内容を確認します。
      1. ゲストOSシェルへアクセスします。           
        AXP(exec-helloworld)> connect console
        bash-2.05b#
      2. pidファイルが正しく作られているか確認します。
        bash-2.05b# ps -ef | grep hello
        root      3105  3104  0 19:29 ?        00:00:00 /bin/bash /opt/helloworld.sh
        bash-2.05b# cat /var/run/helloworld.pid
        3105
      3. W01helloworld.sh の終了コードを確認します。
        bash-2.05b# cd /opt/app_status_monitor/watchdogs/
        bash-2.05b# ./W01helloworld.sh
        bash-2.05b# echo $?
        0
        ここが0以外の場合、ステータスモニタはアプリケーションが機能していないとみなします。

     

    パッケージの削除

    AXP> software uninstall uid-list 0e9114b7-1c97-4edd-aaac-94363fdeeea8