スタートアップスクリプトとは

[更新: 2024年7月4日]

「スタートアップスクリプト」機能についての説明ページです。

1. 概要

スタートアップスクリプトは、新たにサーバを作成する際、任意の「スタートアップスクリプト」を選択することにより、起動時にそれらを自動的に実行する機能です。この機能により、

  • yumコマンドを実行し、必要なアプリケーションがあらかじめインストールされた状態にする
  • 多数のユーザを登録し、起動直後にログインができるようにする
  • サーバ内の各設定を自動的に行う

などの自動化が可能となり、サーバ作成後の設定作業の大幅な軽減や、Sacloud APIと組み合わせた自動スケールアウトシステムなどの構築がより簡単に行えるようになります。

対応OS

AlmaLinux、Rocky Linux、MIRACLE LINUX、Debian、Ubuntu の各バージョンです。

※本機能は弊社提供のパブリックアーカイブに対して動作保証をしております。

クラス

スタートアップスクリプトには以下の2種類があります。この種類のことを「クラス」と呼びます。

クラス 説明
SHELL シェルスクリプトとして記述するスタートアップスクリプト
YAML_CLOUD_CONFIG YAML形式で記述するスタートアップスクリプト

2. スタートアップスクリプトの動作

サーバ作成画面でスタートアップスクリプトを選択すると、起動後のサーバ内で以下の動作が行われます。

SHELLクラス

  1. 起動時、/etc/rc.localが/root/.sacloud-api/startup.shを実行
  2. @sacloud-apikey を利用した場合、 “/root/.sacloud-api/notes/スタートアップスクリプトID_apikey” ファイルから$SACLOUD_APIKEY_ACCESS_TOKENと$SACLOUD_APIKEY_ACCESS_TOKEN_SECRETを環境変数として設定
  3. startup.shが、「スタートアップスクリプト」で指定したスクリプト(“/root/.sacloud-api/notes/スタートアップスクリプトID“に配置)を実行
  4. スクリプトが実行され、ログが”/root/.sacloud-api/notes/スタートアップスクリプトID.log”に出力される
  5. @sacloud-apikey を利用した場合、スクリプトが終了すると、環境変数として設定された$SACLOUD_APIKEY_ACCESS_TOKENと$SACLOUD_APIKEY_ACCESS_TOKEN_SECRETを無効にした後に、”/root/.sacloud-api/notes/スタートアップスクリプトID_apikey” ファイルを削除
  6. 各スクリプトが正しく(終了コードが”0″)終了すると、”/root/.sacloud-api/notes/スタートアップスクリプトID.done”という名前の空ファイルを作成(このファイルが存在すると@sacloud-once を指定したスクリプトは実行されない)
  7. /root/.sacloud-api/server.jsonファイルにサーバの情報が格納されます。

YAML_CLOUD_CONFIGクラス

サーバの起動時、cloud-init に対応したOSの設定が実行されます。

重要

本機能を用いて入力するパスワードを含む入力値は、上記内容のスタートアップスクリプト及び実行ログ、スクリプト内部の処理で作成されるファイルなどに残留します。 パスワードを含む値を削除する必要がある場合には、上記の内容を参考にお客様ご自身にてご対応をお願いいたします。

3. スタートアップスクリプトの登録方法

スタートアップスクリプトの作成・編集は、コントロールパネル「オプション」メニュー内のサイドメニュー「スタートアップスクリプト」から行えます。

コントロールパネル画面右上の「オプション」ボタンをクリックします。

画像ファイル

左のサブメニューより「スクリプト」を選択すると、スタートアップスクリプト管理画面が表示されます。

画像ファイル

初期状態ではさくらインターネット側であらかじめ作成済みの パブリックスクリプト が表示されますが、ユーザが作成したプライベートスクリプトのリストを表示する場合は、上部「プライベート」タブをクリックして切り替えます。

画像ファイル

「追加」ボタンをクリックすると「スタートアップスクリプトを追加」画面が表示されるので、ここでスタートアップスクリプトの名前と内容を入力します。

画像ファイル

入力後、右下の「作成」ボタンをクリックすると、スクリプト管理画面のプライベートスクリプトのリストに追加され、サーバ追加画面の「スタートアップスクリプト」で選択できるようになります。

4. スタートアップスクリプト内で使用できる特殊タグ・変数

スタートアップスクリプト内では、特殊タグを付与して実行条件の制御やフォーム表示機能などが利用できます。

※フォーム表示機能は 新サーバ作成画面 のみでの対応となります。
※以下の特殊タグはパブリックスクリプトのみで使用されます。ユーザーが作成したプライベートスクリプトでは利用できません。

  • @sacloud-name
  • @sacloud-tag の要素の @simplemode
  • @sacloud-tag の要素の @tab-marketplace
  • @sacloud-tag の要素の @logo-alphabet-*
  • @sacloud-tag の要素の @logo-image-*

実行制御・説明表示

スタートアップスクリプトの実行条件の制御や、コントロールパネルに表示される説明文を設定するタグです。

@sacloud-once

コメントとして以下の行を記述すると、起動時に1回のみ(“/root/.sacloud-api/notes/[該当スタートアップスクリプトID].done”ファイルが存在しない時だけ)実行されるようになります。

# @sacloud-once

※この記述がない場合は、サーバを起動するたびに毎回実行されます。
※YAML_CLOUD_CONFIGクラスでは使用できません。

@sacloud-desc / @sacloud-desc-begin / @sacloud-desc-end

ディスク作成画面のスタートアップスクリプト選択欄に説明文として表示される文字列を指定します。それぞれ以下のように使用します。

#!/bin/bash

# @sacloud-desc-begin
#   複数行のコメントです。
#   行頭の空白文字は自動的に最適化されます。
# @sacloud-desc-end

# @sacloud-desc 1行のコメントです。
# @sacloud-desc これらのタグを複数回使用すると、全コメントが連結されます。

@sacloud-require-archive

サーバ作成画面で、指定したOS以外のパブリックアーカイブを選択した場合に警告を表示します。特定のOSのみで動作するスタートアップスクリプトなどに記述することで、想定しない環境へのスクリプト適用を防止することができます。

本特殊タグの記法は以下の通りです。

# @sacloud-require-archive [OS種別指定子] [バージョン指定子]

※OS種別指定子は必須オプションです。バージョン指定子は任意で付与します。

各オプションの指定子は以下の通りです。

OS種別指定子

distro-alma AlmaLinux
distro-rocky Rocky Linux
distro-miracle MIRACLE LINUX
distro-ubuntu Ubuntu
distro-debian Debian/GNU Linux

バージョン指定子

distro-ver-バージョン番号

バージョン番号部には小数点を含む数字、ワイルドカードが指定できます。

例: distro-ver-8 / distro-ver-7.*

記述例

  • Ubuntu Server 20.04系以外のパブリックアーカイブを指定した場合に警告を表示させる
# @sacloud-require-archive distro-ubuntu distro-ver-20.04.*

※このタグはさくらのクラウドで提供されているパブリックアーカイブのみで有効となります。ご自身で作成されたアーカイブでは内容の判定を行うことができないため機能しません。
※APIから操作した場合、警告の表示は行われません。

@sacloud-tag

スタートアップスクリプトのリソースに対してタグを付与します。タグはスペース区切りで複数指定できます。

# @sacloud-tag [タグ名]

この @sacloud-tag に対して @require-core、@require-memory-gib を指定することにより、サーバ作成画面で、指定した仮想コア数、メモリに満たない場合に警告を表示することができます。

記述例

  • 仮想コア数4Core以上、メモリ8GB以上でない場合にサーバ作成画面で警告を表示させる場合
# @sacloud-tag @require-core>=4 @require-memory-gib>=8

埋め込み変数・フォーム部品関連タグ

新規サーバ作成画面での「ディスクの修正」の項目にフォーム部品を表示し、指定した変数にフォーム入力内容が設定されます。

各タグは、以下のような共通のフォーマットで記述されます。

@sacloud-<フォーム種別> [ <オプション> [ <オプション> ... ]] <変数名> <表示ラベル> [ ex=<グレー表示テキスト> ]

フォームに入力された変数は、”@@@変数名@@@“でその内容を参照できます。
オプションはシェル引数のように解釈されるため、空白を含む場合は引用符で括る必要があります。変数名には英数字とアンダースコアのみ使用できます。

※@sacloud-apikey使用時のAPIキーの変数のみ、@@@変数名@@@の形式ではなく、普通の変数形式($変数名)となります。以下の使用例をご参考になさってください。

# @sacloud-apikey required permission=create external_permission=cdn+bill SACLOUD_APIKEY "APIキー"

echo $SACLOUD_APIKEY_ACCESS_TOKEN > /tmp/test.log
echo $SACLOUD_APIKEY_ACCESS_TOKEN_SECRET >> /tmp/test.log

共通オプション

各タグに共通して指定可能なオプションの一覧です。

オプション 説明
required 変数の指定を必須とします。
default=<文字列> デフォルトとして適用する値です。@sacloud-checkbox については、指定されている場合には選択時とみなされます。
shellarg 埋め込み時にシェル引数用にフォーマットされます。基本的には単引用符(‘)で括られます。
heredoc 埋め込み時に複数行に渡る文字列をヒアドキュメントとしてフォーマットします。終端文字列はランダムに生成されます。
indent=<整数値> 埋め込み時に指定した数の空白文字を各行頭に挿入します。ansibleのYAMLに複数行の文字列を埋め込む際などに有用です。

フォーム種別指定タグ

各フォームの種別を指定するタグです。

タグ 説明
@sacloud-text 文字列入力欄(1行)を表示します。
次項「@sacloud-text 専用オプション」の専用オプションが使用できます。
@sacloud-password パスワード入力欄(1行)を表示します。
@sacloud-textarea 文字列入力欄(複数行)を表示します。
@sacloud-select-begin
@sacloud-select-end
ポップアップメニューを表示します。
これらのタグで挟まれた行はそれぞれ値と表示ラベルのペアとして解釈され、選択肢として表示されます。
表示ラベルが省略された場合は値がそのままラベルとして用いられます。
@sacloud-checkboxes-begin
@sacloud-checkboxes-end
チェックボックスグループが表示されます。
これらのタグで挟まれた行はそれぞれ値と表示ラベルのペアとして解釈され、選択肢として表示されます。
複数選択された値は半角スペースで結合されます。
@sacloud-checkbox 単一のチェックボックスを表示します。
非選択時は空文字、選択時は”1″が代入されます。
@sacloud-radios-begin
@sacloud-radios-end
ラジオボタンを表示します。
これらのタグで挟まれた行はそれぞれ値と表示ラベルのペアとして解釈され、選択肢として表示されます。
表示ラベルが省略された場合は値がそのままラベルとして用いられます。
@sacloud-apikey 作成済みのAPIキーを一覧から選択して指定できます。
ACCESS TOKENは$SACLOUD_APIKEY_ACCESS_TOKEN
ACCESS TOKEN SECRETは$SACLOUD_APIKEY_ACCESS_TOKEN_SECRET
という名称の変数に格納されます。YAML_CLOUD_CONFIGクラスでは使用できません。

重要

@sacloud-password で入力したパスワードは、スタートアップスクリプト及び実行ログ、スクリプト内部の処理で作成されるファイルなどに残留します。 パスワードを削除する必要がある場合には スタートアップスクリプトの動作 を参考にお客様ご自身にて削除のご対応をお願いいたします。

@sacloud-apikey 専用オプション

permission=<文字列>

最低限必要なアクセスレベルを指定します。セレクトボックスには指定したアクセスレベル以上のAPIキーのみ表示されるようになります。

指定可能な文字列は下記のとおりです。

  • 無効: none
  • リソース閲覧: view
  • 電源操作: power
  • 設定編集: arrange
  • 作成・削除: create

例:permission=create

external_permission=<文字列>

必要な他サービスへのアクセス権を指定します。

セレクトボックスには指定した他サービスへのアクセス権を持つAPIキーのみ表示されるようになります。 指定可能な文字列は「bill, cdn」です。

+ 区切りで複数指定することが可能です。

例:external_permission=bill+cdn

@sacloud-text 専用オプション

文字列入力欄表示タグ @sacloud-text 専用のオプションです。

オプション 説明
maxlen=<整数値> 文字列として評価したときに受け入れを許可する長さの上限です。
minlen=<整数値> 文字列として評価したときに受け入れを許可する長さの下限です。
ex=<文字列> 未入力状態のテキストボックスにグレー表示するテキストです。
integer 整数値のみを入力できるようにします。
min=<数値> 数値として評価したときに受け入れを許可する最小の値です。
max=<数値> 数値として評価したときに受け入れを許可する最大の値です。

定義済み変数

スクリプト実行時にあらかじめ定義される変数です。

変数名 説明
@@@.ID@@@ ノートIDが設定されます。
@@@.Name@@@ ノート名が設定されます。

5. スタートアップスクリプトの例(SHELLクラス)

各フォーム変数を使用し、bashスクリプトで作成したスタートアップスクリプトの例です。

#!/bin/bash

# @sacloud-once
# @sacloud-text required shellarg maxlen=100 blog_title "ブログタイトル"
# @sacloud-textarea required heredoc maxlen=1000 blog_desc "説明" ex="例:さくらのblogです"
# @sacloud-text integer min=5 max=100 default=5 articles_per_page "ページあたりの記事数"
# @sacloud-radios-begin default=two-r layout "レイアウト"
#     two-r "2カラム(右サイドバー)"
#     two-l "2カラム(左サイドバー)"
#     three "3カラム"
# @sacloud-radios-end
# @sacloud-select-begin default=white theme "デザインテーマ"
#     white "白"
#     red   "赤"
#     wooden
#     crystal
# @sacloud-select-end
# @sacloud-checkboxes-begin default=history,tagcloud home_display "ホーム画面表示項目"
#     history "更新履歴"
#     profile "プロフィール"
#     tagcloud "タグクラウド"
#     twitter "Twitter"
# @sacloud-checkboxes-end
# @sacloud-checkbox default=on allow_comment "コメントを許可する"

BLOG_TITLE=@@@blog_title@@@
ARTICLES_PER_PAGE=@@@articles_per_page@@@
LAYOUT=@@@layout@@@
THEME=@@@theme@@@
HOME_DISPLAY=@@@home_display@@@
ALLOW_COMMENT=@@@allow_comment@@@

cat >/root/test.txt @@@blog_desc@@@
echo $BLOG_TITLE >> /root/test.txt

exit 0

サーバ作成時にこのスクリプトが選択されると以下のようなフォームが表示されます。

画像ファイル

上記の図の入力内容でサーバを作成すると、以下のように変数展開されたスクリプトがディスクに書き込まれます。

#!/bin/bash

# @sacloud-once
# @sacloud-text required shellarg maxlen=100 blog_title "ブログタイトル"
# @sacloud-textarea required heredoc maxlen=1000 blog_desc "説明" ex="例:さくらのblogです"
# @sacloud-text integer min=5 max=100 default=5 articles_per_page "ページあたりの記事数"
# @sacloud-radios-begin default=two-r layout "レイアウト"
#     two-r "2カラム(右サイドバー)"
#     two-l "2カラム(左サイドバー)"
#     three "3カラム"
# @sacloud-radios-end
# @sacloud-select-begin default=white theme "デザインテーマ"
#     white "白"
#     red   "赤"
#     wooden
#     crystal
# @sacloud-select-end
# @sacloud-checkboxes-begin default=history,tagcloud home_display "ホーム画面表示項目"
#     history "更新履歴"
#     profile "プロフィール"
#     tagcloud "タグクラウド"
#     twitter "Twitter"
# @sacloud-checkboxes-end
# @sacloud-checkbox default=on allow_comment "コメントを許可する"

BLOG_TITLE='さくらインターネットブログ'
ARTICLES_PER_PAGE=20
LAYOUT=three
THEME=red
HOME_DISPLAY='history profile tagcloud'
ALLOW_COMMENT=1

cat >/root/test.txt <<'HD_538ed94b2dafd'
さくらインターネット株式会社のブログです。
弊社サービスの最新情報などをお届けします。
HD_538ed94b2dafd

echo $BLOG_TITLE >> /root/test.txt

exit 0

7. server.jsonファイルに出力される情報一覧

server.jsonファイルは /root/.sacloud-api/server.json に配置されます。

ファイルに出力される情報は以下の通りです。

{
  "Tags": [
    "@virtio-net-pci"
  ],
  "Interfaces": [
    {
      "PacketFilter": null,
      "Switch": {
        "UserSubnet": null,
        "Subnet": {
          "Internet": {
            "BandWidthMbps": 100
          },
          "DefaultRoute": "[デフォルトゲートウェイのIPアドレス]",
          "NetworkMaskLen": 24,
          "NetworkAddress": "[ネットワークアドレス]",
          "ID": null
        },
        "Scope": "shared",
        "Name": "スイッチ",
        "ID": "[NICが接続されている先のリソースID]"
      },
      "HostName": null,
      "UserIPAddress": null,
      "IPAddress": "[NICのIPアドレス]",
      "MACAddress": "[NICMACアドレス]",
      "ID": "[NICのリソースID]"
    }
  ],
  "Disks": [
    {
      "BundleInfo": null,
      "Storage": {
        "Class": "iscsi1204",
        "MountIndex": 2100194006,
        "ID": 2100194006
      },
      "ID": "[ディスクのリソースID]",
      "Name": "[ディスクの名前]",
      "Connection": "virtio",
      "ConnectionOrder": 1,
      "ReinstallCount": 0,
      "Availability": "available",
      "SizeMB": 20480,
      "Plan": {
        "ID": 4
      }
    }
  ],
  "Zone": {
    "Region": {
      "NameServers": [
        "[ネームサーバのIP1]",
        "[ネームサーバのIP2]"
      ],
      "Description": "東京",
      "Name": "東京",
      "ID": 210
    },
    "FTPServer": {
      "IPAddress": "27.133.143.244",
      "HostName": "sac-tk1a-ssl.sakura.ad.jp"
    },
    "VNCProxy": {
      "IPAddress": "27.133.143.244",
      "HostName": "sac-tk1a-ssl.sakura.ad.jp"
    },
    "IsDummy": false,
    "Description": "東京第1ゾーン",
    "Name": "tk1a",
    "DisplayOrder": 20021001,
    "ID": 21001
  },
  "ServerPlan": {
    "ServiceClass": "cloud/plan/1core-1gb",
    "MemoryMB": 1024,
    "CPU": 1,
    "Name": "プラン/1Core-1GB",
    "ID": 1001
  },
  "ID": "[サーバのリソースID]",
  "Name": "[サーバの名前]",
  "HostName": "localhost",
  "Description": "",
  "Availability": "available",
  "ServiceClass": "cloud/plan/1core-1gb",
  "CreatedAt": "2016-05-10T10:52:59+09:00",
  "Icon": {
    "Scope": "shared",
    "Name": "CentOS",
    "URL": "https://secure.sakura.ad.jp/cloud/zone/tk1a/api/cloud/1.1/icon/112300511981.png",
    "ID": "112300511981"
  }
}

8. 設定済みスタートアップスクリプト

さくらのクラウドでは、すぐにお使いいただける設定済みの便利なスクリプトをいくつか用意しています。

詳しくは パブリックスクリプト のページを参照ください。