CDEMU(1)

NAME
cdemu - a simple command-line CDEmu client

SYNOPSIS
cdemu [options] <command> <command parameters>

DESCRIPTION
This is cdemu, a command-line client for controlling CDEmu daemon. It is part of the cdemu suite, a free, GPL CD/DVD-ROM device emulator for linux.

It provides a way to perform the key tasks related to controlling the CDEmu daemon, such as loading and unloading devices, displaying devices' status and retrieving/setting devices' debug masks.

When connecting to daemon, cdemu client can use either session or system bus. By hard-coded default, it uses session bus. The default bus to be used can be specified via /etc/cdemu-client.conf or ~/.cdemu-client file; for more information, please read README file. The default can be overridden using --bus option.

ENCRYPTED IMAGES SUPPORT
CDEmu daemon offers support for encrypted images. When password is required to load an image, cdemu-client will prompt for it and then send it to daemon.

NOTE, HOWEVER, THAT THE PASSWORD IS SENT OVER D-BUS IN A PLAIN STRING FORM, WITHOUT ANY PROTECTION.

The password prompt mechanism is implemented as follows. If CDEMU_ASKPASS environment variable is set, the password is obtained by running a sub-process with the command specified in the said environment variable. Otherwise, if the client is ran from a console (standard input is available), the console is used to prompt for the password. If console is unavailable, the command from SSH_ASKPASS environment variable is used, if the said variable is set. Otherwise, the password cannot be obtained and error is raised.

OPTIONAL INTEGRATION WITH ZENITY
Optional integration with zenity can be turned on by setting the CDEMU_USE_ZENITY environment variable to a value different from 0.

In this mode, cdemu client uses zenity-provided password input dialog to prompt user for password when trying to load an encrypted image. This effectively bypasses the mechanism outlined in the previous section (i.e., the zenity dialog is always used to prompt for password, regardless of other environment variables and availability of standard input).

Similarly, zenity-provided error dialog is used to report errors, in addition to them being printed to the stderr stream. Note that error dialog effectively blocks the execution of the program until user acknowledges and closes the dialog.

This mode is primarily intended for use cases where cdemu client is used to implement actions that run without attached console, but may require user input (password) and may need to report error messages. An example of such scenario is implementation of a "Load with CDEmu client" action for desktop environments and their file browsers.

OPTIONS

-h --help
    Displays the help message. If command is specified, help message with synopsis and description for that command is displayed.

-v --version
    Prints version info and exits.

-b --bus
    Sets the D-BUS bus type to use for connection. Valid values are session and system. If no bus is specified, the session bus is used by default.

COMMANDS

load [options] <device> <filename> [...]
    Loads the device; device is the number of the desired device, or any. If any is used, then the client will attempt to load the image into the first empty device it finds (provided there is one available). filename is the image filename. For multi-file images, multiple filenames can be provided. The following options can be passed to the load command: --replace (or --unload) Allows the specified device to be unloaded, thereby effectively replacing the image in an already-loaded device. When device is set to any, the client first iterates over all devices and attempts to find an empty device. If no empty device is available, it iterates over devices again, and attempts to load the image in first device that it manages to unload. In practice, this will most often be the first device, unless some explicit locking prevents the device from being unloaded. --create If no empty device is available, allow client to request a new device to be created, and load the image into it. Applicable only when device is set to any. In addition to the above options, the following optional parser parameters can be also passed via corresponding options (whether they are supported by a particular image parser or not depends on the parser implementation): --encoding <string> Allows an encoding for text-based image format (such as CUE) to be specified. This might be needed if the image descriptor file contains non-ASCII characters and does not use Unicode.

create-blank [options] --writer_id=<writer-id> <device> <image_file>
    Creates blank recordable disc in the specified device. device is the number of the desired device, or any. If any is used, then the client will attempt to load the image into the first empty device it finds (provided there is one available). image_file is the image filename/basename. A valid writer-id must also be provided. Other valid options are: --medium-type <type> Sets the blank medium type. Valid values are: cdr74, cdr80, cdr90, cdr99 and dvd+r. --param="writer.parameter_id=parameter_value" Allows user to pass additional image writer parameters. parameter_id must be a valid parameter ID from image writer's parameter sheet, prefixed by "writer.".

unload <device>
    Unloads the device; device is the number of the desired device, or all.

status
    Displays devices' status

add-device
    Creates another virtual device

remove-device
    Removes the last virtual device

device-mapping
    Displays device mapping information

daemon-debug-mask <device> [new-value]
    Displays/sets daemon debug mask; device is the number of the desired device, or all. new-value is the new debug mask value. If this argument is omitted, current debug mask is displayed. The list of supported debug mask identifiers and values can be obtained with enum-daemon-debug-masks command. The new-value can be either a single numeric value (e.g, 0x03), a string of numeric values separated by pipe character (e.g., "0x01|0x02"), or a string of identifiers separated by pipe character (e.g., "DAEMON_DEBUG_DEVICE|DAEMON_DEBUG_MMC").

library-debug-mask <device> [new-value]
    Displays/sets library debug mask; device is the number of the desired device, or all. new-value is the new debug mask value. If this argument is omitted, current debug mask is displayed. The list of supported debug mask identifiers and values can be obtained with enum-library-debug-masks command. The new-value can be either a single numeric value (e.g, 0x03), a string of numeric values separated by pipe character (e.g., "0x01|0x02"), or a string of identifiers separated by pipe character (e.g., "MIRAGE_DEBUG_PARSER|MIRAGE_DEBUG_DISC").

dpm-emulation <device> [new-value]
    Displays/sets DPM emulation flag. device is the number of the desired device, or all. new-value is the new value to be set. If this argument is omitted, currently set value is displayed.

tr-emulation <device> [new-value]
    Displays/sets transfer rate emulation flag. device is the number of the desired device, or all. new-value is the new value to be set. If this argument is omitted, currently set value is displayed.

bad-sector-emulation <device> [new-value]
    Displays/sets bad sector emulation flag. device is the number of the desired device, or all. new-value is the new value to be set. If this argument is omitted, currently set value is displayed.

dvd-report-css <device> [new-value]
    Report the loaded DVD as CSS-encrypted. device is the number of the desired device, or all. new-value is the new value to be set. If this argument is omitted, currently set value is displayed. This flag influences the generation of fake Disc Structure 0x01, and as such works only with images of DVD videos that do not provide this information (most images, with exception of perhaps mds/mdf, don't). Enabling this option allows images of CSS-encrypted DVDs (e.g. created using 'dd' or 'readcd' without running through a CSS decryption step when creating the image) to be played by a deCSS-enabled Linux media player.

device-id <device> [new-vendor-id] [new-product-id] [new-revision] [new-vendor-specific]
    Displays/sets device ID. device is the number of the desired device. new-vendor-id is the new vendor ID string to be set (8 characters max). new-product-id is the new product ID string to be set (16 characters max). new-revision is the new revision string to be set (4 characters max). new-vendor-specific is the new vendor-specific string to be set (20 characters max). If new values are omitted, currently set values are displayed.

enum-parsers
    Enumerates supported image parsers.

enum-writers
    Enumerates supported image writers.

enum-filter-streams
    Enumerates supported filter streams.

enum-daemon-debug-masks
    Enumerates supported daemon debug masks.

enum-library-debug-masks
    Enumerates supported library debug masks.

enum-writer-parameters <writer-id>
    Retrieves and displays parameters sheet for specified image writer.

version
    Displays version information

EXAMPLES

Loading a single image to first device:
    cdemu load 0 ~/image.mds

Loading multiple-file image to first device:
    cdemu load 0 ~/session1.toc ~/session2.toc ~/session3.toc

Loading a text-based image in non-ASCII/non-Unicode encoding:
     cdemu load 0 ~/image.cue --encoding=windows-1250

Loading a raw image of a CSS-encrypted DVD created by 'dd', so it can be played by mplayer:
     cdemu load 0 ~/image.iso
     cdemu dvd-report-css 0 1

Creating a blank recordable disc: DVD+R SL with ISO image writer:
    cdemu create-blank --writer-id=WRITER-ISO --medium-type=dvd+r 0 ~/output-image.iso

Creating a blank recordable disc: 80-minute CD-R with TOC image writer, with additional writer parameters:
    cdemu create-blank --writer-id=WRITER-TOC --medium-type=cdr80 --param="writer.write_raw=1" --param="writer.write_subchannel=1" 0 ~/output-image.toc

Unloading first device:
    cdemu unload 0

Displaying device status:
    cdemu status

Adding another device:
    cdemu add-device

Removing the last device:
    cdemu remove-device

Displaying device mapping information:
    cdemu device-mapping

Setting daemon debug mask for the first device:
    cdemu daemon-debug-mask 0 0x01

Setting daemon debug mask for the first device (composite):
    cdemu daemon-debug-mask 0 "0x01|0x02"

Setting daemon debug mask for the first device (composite, by name):
    cdemu daemon-debug-mask 0 "DAEMON_DEBUG_DEVICE|DAEMON_DEBUG_MMC"

Obtaining library debug mask for the first device:
    cdemu library-debug-mask 0

Disabling DPM emulation on all devices:
    cdemu dpm-emulation all 0

Enabling transfer rate emulation on first device:
    cdemu tr-emulation 0 1

Enabling bad sector emulation on first device:
    cdemu tr-emulation 0 1

Changing device ID of first device:
    cdemu device-id 0 "MyVendor" "MyProduct" "1.0.0" "Test device ID"

Enumerating supported image parsers:
    cdemu enum-parsers

Enumerating supported image writers:
    cdemu enum-writers

Enumerating supported filter streams:
    cdemu enum-filter-streams

Enumerating supported daemon debug masks:
    cdemu enum-daemon-debug-masks

Enumerating supported library debug masks:
    cdemu enum-library-debug-masks

Obtaining parameter sheet for TOC image writer:
    cdemu enum-writer-parameters WRITER-TOC

Displaying daemon and library version:
    cdemu version

AUTHORS

Rok Mandeljc <rok.mandeljc@gmail.com>

CDEmu project's web page: http://cdemu.sourceforge.net

CDEmu project's mailing list: cdemu-devel@lists.sourceforge.net