6.4. Host Commands

6.4. Host Commands
Prev	Chapter 6. Basic Agent Reference	Next

All of the host commands take a host_names parameter. This can be a single host name or IP address or a list of them enclosed in double quotes and separated by spaces (e.g. “1.2.3.4 w.x.y.z”), or simply a pair of double quotes, which means to use all of the machines in a cluster.

6.4.1. bid

tycoon host bid host_names [duration [[preference0 preference1 ...]]

duration: This is the bid duration as described in Section 4.2, “Bid Semantics and Syntax”. If not specified, this remains unchanged.
preference: This is a bid preference as described in Section 4.2, “Bid Semantics and Syntax”. If not specified, this remains unchanged.

This sets the bid for the user's host account at the specified providing host. The auctioneer will allocate all of the host account's funds to be spent by the expiration time. Note that this operation is faster than tycoon host fund because it does not involve communication with the bank. As a result, it is better to use this if you are not adding funds.

6.4.2. boot

tycoon host boot host_names

This boots the virtual machine for the user's default host account on the specified providing host(s). This is useful if the user had previously shut down the virtual machine would now like to start running again. Note that previously running programs will not be restarted unless they are explicitly configured to do so.

6.4.3. create_account

tycoon host create_account host_names initial_deposit [duration [[preference0 preference1 ...]]

initial_deposit: This is the initial amount to be deposited in the new account. Only integer amounts are allowed.
duration: This is the bid duration as described in Section 4.2, “Bid Semantics and Syntax”. If not specified, this defaults to 1G seconds (31.7 years).
preference: This is a bid preference as described in Section 4.2, “Bid Semantics and Syntax”. If not specified, this defaults to 0%-100% of the CPU, 128MB of memory, and 1G of disk (all with a weight of 1).

This creates an account at the specified host. Note that this command can take several minutes because a file system must be created and populated. Once created, the auctioneer will boot the virtual machine for this host account.

The user can also specify which file system image should be used to create the virtual machine. If no image is specified, the auctioneer will use its default image. File system images can be specified as follows:

Using a remote URL, e.g.,

tycoon host create_account host1 1 0 \
    file_system:http://tycoon.hpl.hp.com/~tycoon/dl/images/centos.5-0.ext3.bz2

Using a relative path to a file on the local file system, e.g.,

tycoon host create_account host1 1 0 file_system:file://centos.5-0.ext3

Using an absolute path to a file on the local file system, e.g.,

tycoon host create_account host1 1 0 \
    file_system:file:///var/lib/tycoon/aucd/Xen303/lib/centos.5-0.ext3

Using the default image, e.g.,

tycoon host create_account host1 1 0 file_system:file://default

As a security precaution, auctioneers will only use images from a limited set of URLs and file system paths. The file system image can be compressed using bzip2, zip, or gzip.

6.4.4. delete_account

tycoon host delete_account host_names

This deletes the user's account on the remote machine. This deletes all of the user's files there and refunds the remaining funds.

6.4.5. fund

tycoon host fund host_names fund_amount [duration [[preference0 preference1 ...]]

fund_amount: This is number of credits to transfer to the host account. Only integer amounts are allowed.
duration: This is the bid duration as described in Section 4.2, “Bid Semantics and Syntax”. If not specified, this remains unchanged.
preference: This is a bid preference as described in Section 4.2, “Bid Semantics and Syntax”. If not specified, this remains unchanged.

This funds the user's default host account at the specified providing host. The specified funds are transferred to the host's account. The auctioneer will allocate all of the host account's funds to be spent by the expiration time. Note that this command will perform a separate communication with the bank before communicating with the auctioneer, and therefore is less efficient than just using the "tycoon host bid" command.

6.4.6. get_status

tycoon host get_status host_names [field1] [field2[subfield2.1][subfield2.2]] ...

field1: These are the fields to print out.
field2[subfield2.1][subfield2.2]: Some fields are structured. To access the subfields, specify the subfield names with brackets. For example, to access information on IP address resources, use the field string "resources[IPv4Address][1][addresses]".

This gets the status of the providing host(s). The includes all the non-host account-specific information, like the availability of resources. Unlike other commands in this Chapter, this command does not require the user to have a host account at the providing host(s). Here are some commonly used fields:

owner_account: This is the owner of the host.
owner_public_key: This is the public key of the owner of the host.
resources.: These are the resources on the host.

6.4.7. get_account_status

tycoon host get_account_status host_names [field1] [field2[subfield2.1][subfield2.2]]

field1: These are the fields to print out.
field2[subfield2.1][subfield2.2]: Some fields are structured. To access the subfields, specify the subfield names with brackets. For example, to access information on IP address resources, use the field string "resources[IPv4Address][1][addresses]".

This prints the status of the user's host account at the providing host(s). This includes all of the information returned by tycoon host get_status. Here are some commonly used fields:

balance: This is the amount of currency remaining in the host account.
bid: This is the current bid for the host account.
deposited: This is the total amount of currency deposited into the account.
expiration: This is the time in seconds from the UNIX epoch to when the bid will expire.
file_system_size: This is the size of the file system in bytes.
interval: This is the duration of the bid.
spent: This is the total amount of currency spent in the account.
state: This is the state of the virtual machine: running or shutdown.
withdrawn: This is the total amount of currency withdrawn from the account.

6.4.8. query_accounts

tycoon host query_accounts host_names [sql_query]

sql_query ...: This is an SQL query on the auctioneers' host account database.

This queries the host accounts on the specified resource-providing hosts. If the user is not the owner of the auctioneer, then this command returns the host accounts that are owned by the user's default bank account. This is useful when users forget what host accounts they have on a host. If the user is the owner of the auctioneer, then he or she can issue SQL queries against the auctioneer's account database. This is useful for determining which bank accounts own which host accounts and which host accounts have which IP addresses, among other tasks.

6.4.9. refund

tycoon host refund host_names refund_amount [duration [[preference0 preference1 ...]]

refund_amount: This is number of credits to transfer from the host account. Only integer amounts are allowed.
duration: This is the bid duration as described in Section 4.2, “Bid Semantics and Syntax”. If not specified, this remains unchanged.
preference: This is a bid preference as described in Section 4.2, “Bid Semantics and Syntax”. If not specified, this remains unchanged.

This command refunds money from the user's account at the specified host. To refund all the funds, specify "all" as the fund amount. Note that since only integer amounts are allowed, a fractional unrefundable amount may be left on the host.

6.4.10. set

tycoon host set host_names field value

This command changes the value of a field of the user's account at the specified host. The following fields can be used:

append_owner

Add an owner to the host account. The new owner has all the privileges of the original owner. The value is a list containing the new owner's name and public key. Example:

$ tycoon host set providing_host append_owner "['tycoon_chris','MIIBuDCCASwGByqGSM44BAEwggEfAoGBAP1/U4EddRIpUt9KnC7s5Of2EbdSPO9EAMMeP4C2USZpRV1AIlH7WT2NWPq/xfW6MPbLm1Vs14E7gB00b/JmYLdrmVClpJ+f6AR7ECLCT7up1/63xhv4O1fnxqimFQ8E+4P208UewwI1VBNaFpEy9nXzrith1yrv8iIDGZ3RSAHHAhUAl2BQjxUjC8yykrmCouuEC/BYHPUCgYEA9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJFnEj6EwoFhO3zwkyjMim4TwWeotUfI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6Ae1UlZAFMO/7PSSoDgYUAAoGBAPq0NyUqsYA/X0P6jPB4wtfMHhdYjjg0w0mZD2uh7J9h3SNEdzWh9sJlLjqzrfwz6kefYMAefU5kR0TjYI8NXtSmp/ZYJvahRYM3UoxuxV2SStj49/qdRLelkdDiD25zQ+QXhDU2q5YPbM2RHWynmaAmTl9V9R5Vx0uw1rUDD2z7']"

remove_owner

Remove an owner from the host account. The value is the owner's name. Example:

$ tycoon host set providing_host remove_owner tycoon_chris

file_system_size

This changes the file system size of the host account. The value string is the new size of the file system. Examples are "1GB", "1GiB", and "max". "max" indicates that the new size should be the maximum possible given the current bid, which will be somewhat less than the bid size because of file system overhead. See Section 5.1, “Managing Disk” for how to use this to manage file system sizes.

6.4.11. shutdown

tycoon host shutdown host_names [timeout]

timeout: This specifies how long to wait before forcefully terminating the virtual machine. If not specified, this defaults to 30s.

This shuts down the virtual machine for the user's default host account on the specificed providing host(s). This is useful if the user is not going to run on the providing host for a while and wishes to minimize the consumption of credits.

6.4.12. Error Messages

XXX List error messages here

Prev	Up	Next
6.3. Service Location Commands	Home	6.5. Configuration