Ubuntu Wiki

u1sdtool is a command-line application that can be used to start, interact and shutdown Ubuntu One file synchronization service (ubuntuone-syncdaemon).

This page describes u1sdtool as appears in 3.0.0-0ubuntu1 version of ubuntuone-client as shipped in Ubuntu 12.04 (Precise Pangolin).

Under Windows, the u1sdtool.exe application is located in \Program Files\ubuntuone\dist\u1sdtool.exe and accepts the same options as the Ubuntu version. In Ubuntu u1sdtool is available from ubuntuone-client package and installs itself to /usr/bin/u1sdtool.

Usage: u1sdtool [option]

Options:
  -h, --help            show this help message and exit
  -w, --wait            Wait until ubuntuone-syncdaemon reaches nirvana
  --accept-share=SHARE_ID
                        Accept the share with the specified id
  --reject-share=SHARE_ID
                        Reject the share with the specified id
  --list-shares         Get the list of shares
  --subscribe-share=SHARE_ID
                        Subscribe to a share specified by id
  --unsubscribe-share=SHARE_ID
                        Unsubscribe from a share specified by id
  --refresh-shares      Request a refresh of the list of shares to the server
  --offer-share=PATH USER SHARE_NAME ACCESS_LEVEL
                        Share PATH to USER.
  --list-shared         List the shared paths/shares offered.
  --create-folder=PATH  Create user defined folder in the specified path
  --delete-folder=FOLDER_ID
                        Delete user defined folder in the specified path
  --list-folders        List all the user defined folders
  --subscribe-folder=FOLDER_ID
                        Subscribe to the folder specified by id
  --unsubscribe-folder=FOLDER_ID
                        Unsubscribe from the folder specified by id
  --refresh-volumes     Request a refresh of the list of volumes to the server
  --rescan-from-scratch=VOLUME_ID
                        Request a rescan from scratch for a volume.
  --publish-file=PATH   Publish file publicly.
  --unpublish-file=PATH
                        Stop publishing file publicly.
  --info=PATH           Request the metadata of PATH
  --list-dirty-nodes    Show the list of nodes marked as 'dirty'
  --current-transfers    show the current uploads and downloads
  -q, --quit            Shutdown the syncdaemon
  -c, --connect         Connect the syncdaemon
  -d, --disconnect      Disconnect the syncdaemon
  -s, --status          Get the current status of syncdaemon
  --waiting             Get the list of operations being executed
  --waiting-content     Get the waiting content list - Warning: this option is
                        deprecated, use '--waiting' instead
  --waiting-metadata    Get the waiting metadata list - Warning: this option
                        is deprecated, use '--waiting' instead
  --free-space=VOLUME_ID
                        Get the free space for the volume
  --start               Start syncdaemon if it's not running
  --version             Print the version number and exit

• -h, --help: Show usage information (as above)

• -w, --wait: Wait for "nirvana". Requests syncdaemon to reply when it reaches the combination of the following: Syncdaemon is online, no pending requests in the queue and no requests were made for last 5 seconds. At the moment it is not usable due to LP:989160.

• --accept-share=SHARE_ID: Accept a share from another user with a specified ID. The ID can be found in --list-shares output and is a UUID

• --reject-share=SHARE_ID: Reject a share offered. See above for ID

• --list-shares: List all shares offered and their state. Example output:

      id=309f1b01-001d-4568-b8d0-1395779ae0ab name=photos accepted=True \
               subscribed=True access_level=Modify from=openiduser19154

  • id is a SHARE_ID

  • name is a share name

  • accepted is a flag showing whether share has already been accepted.

  • subscribed is a flag showing whether the changes to the remote directory will be synced.

  • access_level can be Modify (read/write access) or Read (read-only access).

  • from is the internal user-name or OpenID identifier of the user offering the share.

• --subscribe-share=SHARE_ID: Enable synchronization for the SHARE_ID specified

• --unsubscribe-share=SHARE_ID: Disable synchronization for the SHARE_ID specified. Already downloaded files will remain on the disk but no changes in the remote folder will be synchronized.

• --refresh-shares: Request the client to obtain the list of shares from the server.

• --offer-share=PATH USER SHARE_NAME ACCESS_LEVEL: Offer a share to another user.

  • PATH is a full path to the folder being shared

  • USER is an E-Mail address of the user that is being offered this share

  • SHARE_NAME is a name given to the shared folder (can be different from the actual folder name of PATH).

  • ACCESS_LEVEL can be "Read" or "Modify" (please note that the first letter is capital).

• --list-shared: List shares that you have offered to other users. Example output:

  Shared list:
    id=197b6da0-a339-4fd7-84db-3a5d98897fc0 name=Documents\
                       accepted=True access_level=Modify to=https://login.ubuntu.com/+id/RwLWeWF \
                       path=/home/rtg/Documents/Shared

• --create-folder=PATH: Create and subscribe a local folder for Ubuntu One synchronization. This folder is will be called UDF, User Defined Folder. PATH must be a full path to the folder and can't be a subdirectory of already existing synchronized folder. For example if you already synchronize /home/username/Documents, you cannot create another UDF in /home/username/Documents/Scans.

• --delete-folder=FOLDER_ID: Ubsubscribe and delete a UDF. The FOLDER_ID can be obtained by running --list-folders. The local files in the folder will be kept intact.

• --list-folders: List all the user defined folders. Example output:

  Folder list:
    id=a7d9ede4-85b9-4990-8b4b-33ef1df2ac4b subscribed=True path=/home/rtg/Sent to Ubuntu One
    id=8ab8a655-be6c-44b0-b628-a781b6eb7be6 subscribed=False path=/home/rtg/deja-dup/buzz

  • id is a FOLDER_ID, subscribed is a flag showing whether the folder will be synchronized with a local storage and path the path that this UDF is being synchronized to or will be synchronized to when subscribed.

• --subscribe-folder=FOLDER_ID: Enable synchronization for the FOLDER_ID specified.

• --unsubscribe-folder=FOLDER_ID: Disable synchronization for the FOLDER_ID specified. Already downloaded files will be kept intact.

• --refresh-volumes: Request the client to obtain the list of the UDFs from the server.

• --rescan-from-scratch=VOLUME_ID: Perform a rescan of the folder and ensure the local folder is the same as the remote one clobbering (overwriting) the local data. This is one-way synchronization, in case some local file is not synchronized properly, running a rescan from scratch will remove the local file.

• --publish-file=PATH: Publish the already synchronized file and get a public link:

  rtg@delorean:~/Ubuntu One$ u1sdtool --publish test-file.txt 
  File is published at http://ubuntuone.com/7D81ANzZmk0sWb6JlBzrmG

• --unpublish-file=PATH: Remove public access to an already synchronized file.

• --info=PATH: Request and show the metadata about PATH:

  File: /home/rtg/Ubuntu One/test-file.txt
    crc32: 1880114715
    generation: 44863
    info_created: 1336646514.72
    info_is_partial: False
    info_last_uploaded: 1336735069.95
    info_node_id_assigned: 1336646515.09
    is_dir: False
    local_hash: sha1:8dd04dbdc09e4b0c967e4199cbf5eb28ad984e2c
    mdid: cccfeae2-1586-403c-bcfc-f85c0d490029
    node_id: 51a11036-7033-4d16-a677-c9e6df32f699
    path: /home/rtg/Ubuntu One/test-file.txt
    server_hash: sha1:8dd04dbdc09e4b0c967e4199cbf5eb28ad984e2c
    share_id: 
    size: 24
    stat: posix.stat_result(st_mode=33204, st_ino=20973970,
                           st_dev=2049L, st_nlink=1, st_uid=1000,
                           st_gid=1000, st_size=24, st_atime=1336735060,
                           st_mtime=1336735069, st_ctime=1336735069)

• --list-dirty-nodes: List nodes that are marked as dirty. A dirty node is a node which can not have the generation delta applied and will require running a rescan from scratch. This is an exceptional condition.

• --current-transfers: Show the list of file uploads and downloads being performed at the moment.

• -q, --quit: Requests ubuntuone-syncdaemon to terminate

• -c, --connect: Requests ubuntuone-syncdaemon to connect to the server

• -d, --disconnect: Requests ubuntuone-syncdaemon to disconnect from the remote server. Please note that disconnect may not be immediate and wait for the current file transfer to continue.

• -s, --status: Show current ubuntuone-syncdaemon status:

  State: QUEUE_MANAGER
      connection: With User With Network
      description: processing the commands pool
      is_connected: True
      is_error: False
      is_online: True
      queues: IDLE

• --waiting: Show list of operations that are in commands pool.

• --waiting-content, --waiting-metadata: Earlier ubuntuone-syncdaemon versions were executing metadata queue first (e.g. creating all the directories and file placeholders first, then starting to upload the actual content). These serve as backward-compatible switches now since more than one queue item may be executed at a time now.

• --free-space=VOLUME_ID: Requests ubuntuone-syncdaemon to retrieve the up-to-date list of volumes and show the amount of bytes free in the Ubuntu One directory, UDF or Share specified by VOLUME_ID.

• --start: Starts ubuntuone-syncdaemon if it is not already running

• --version: Show current version of the client.

~/Ubuntu One volume

The default volume (internally called "root") is available as ~/Ubuntu One folder. Whenever you need to supply the VOLUME_ID and you want to use the root volume, you will need to supply an empty string:

$ # Find out how much space is left in ~/Ubuntu One:
$ u1sdtool --free-space=''
Free space: 54140590616 bytes

Metadata information

File: /home/rtg/Ubuntu One/test-file.txt
  crc32: 1880114715
  generation: 44863
  info_created: 1336646514.72
  info_is_partial: False
  info_last_uploaded: 1336735069.95
  info_node_id_assigned: 1336646515.09
  is_dir: False
  local_hash: sha1:8dd04dbdc09e4b0c967e4199cbf5eb28ad984e2c
  mdid: cccfeae2-1586-403c-bcfc-f85c0d490029
  node_id: 51a11036-7033-4d16-a677-c9e6df32f699
  path: /home/rtg/Ubuntu One/test-file.txt
  server_hash: sha1:8dd04dbdc09e4b0c967e4199cbf5eb28ad984e2c
  share_id: 
  size: 24
  stat: posix.stat_result(st_mode=33204, st_ino=20973970,
                         st_dev=2049L, st_nlink=1, st_uid=1000,
                         st_gid=1000, st_size=24, st_atime=1336735060,
                         st_mtime=1336735069, st_ctime=1336735069)

• crc32: crc32 checksum of the file content

• generation: A special counter which shows at which volume generation this file has changed. This is used to speed-up the server rescan.

• info_created: The unix epoch time (seconds from Jan 1 1970) at which the metadata node was created.

• info_is_partial: A flag showing whether this node is partial, no longer used

• info_last_uploaded: The unix epoch time at which the file content was last uploaded

• info_node_id_assigned: The unix epoch time at which the client has first seen the file/directory being described.

• is_dir: Whether this node is a directory

• local_hash: sha1 hash of the file content as calculated by the client

• mdid: Internal metadata node id

• node_id: The node identifier attached to the current file/directory being described.

• path; The full path to the local file being described.

• server_hash: sha1 hash of the file content as calculated by server. If local_hash and server_hash are different, that means the file is not synchronized.

• share_id: VOLUME_ID of the directory the file is in. For root Ubuntu One folder that is an empty string.

• size: file size in bytes.

• stat: The stored information about the file attributes as returned by python os.stat() call.