This page contains documentation for the ISCSI class and its subclasses:
ISCSI
Overview
Abstract wrapper class for SYNO.Core.ISCSI.* requests.
LUN
Overview
API wrapper for Synology iSCSI LUN management. This class targets the SYNO.Core.ISCSI.LUN WebAPI.
Methods
- Getters :
- List LUNs
- Get LUN details
- Setters :
- Update LUN properties
- Actions :
- Create / delete LUN
- Clone LUN
- Map / unmap targets
Methods
create
Create a new iSCSI LUN.
Internal API
SYNO.Core.ISCSI.LUN
Parameters
name str
LUN name.
type {"FILE","THIN","ADV","BLUN","BLUN_THICK",...}
LUN type. Availability depends on filesystem and DSM version.
location str
Target location, typically a volume path (example: "/volume1").
size int or str
LUN size in bytes.
description str
Optional textual description.
extent_size int or str
Extent size (may be ignored depending on type). [Untested]
emulate_caw bool
Enable SCSI COMPARE AND WRITE (CAW) support.
Allows atomic compare-and-write operations, typically used
by clustered filesystems or applications requiring
conditional block updates. When enabled, the LUN reports
support for the CAW command to the initiator.
emulate_3pc bool
Enable SCSI Third-Party Copy (XCOPY) support.
Allows block-level offloaded copy operations between
devices without transferring data through the initiator.
Used by hypervisors and storage-aware backup systems.
emulate_tpu bool
Enable SCSI UNMAP support (Thin Provisioning UNMAP).
Allows the initiator to explicitly deallocate logical
block ranges that are no longer in use (e.g. filesystem
discard/TRIM). Required for proper space reclamation
on thin-provisioned LUNs.
emulate_tpws bool
Enable SCSI WRITE SAME support with thin provisioning
semantics (Thin Provisioning WRITE SAME).
Allows large zero-write operations that may be interpreted
by the storage backend as deallocation hints. Often used
as an alternative or complement to UNMAP for space
reclamation.
emulate_fua_write bool
Enable handling of the SCSI Force Unit Access (FUA) bit
on write commands (DSM 7+).
When enabled, write commands marked with FUA are forced
to stable storage before completion is reported. Disabling
this may improve performance but can weaken durability
guarantees.
emulate_sync_cache bool
Enable support for the SCSI SYNCHRONIZE CACHE command
(DSM 7+).
When enabled, explicit cache flush requests from the
initiator are honored, ensuring that buffered writes are
committed to stable storage. Disabling this may increase
performance at the cost of reduced crash-consistency
guarantees.
can_snapshot bool
Enable snapshot capability for the LUN.
When set, the LUN is eligible for snapshot creation and
snapshot-based operations (e.g. cloning, replication).
Valid only for thin-provisioned LUN types.
src_lun_dir str
Source lun directory (likely) for creation based on snapshot import.
src_lun_file str
Source lun file (likely) for creation based on snapshot import.
Returns
dict[str, object]
API response.
Example return
Click to expand
{
"data": {
"lun_id": 0,
"uuid": "2e349f91-e2a4-45dc-ba1c-774eb80d8b6f"
},
"success": true
}
delete
Delete one or more LUNs.
Internal API
SYNO.Core.ISCSI.LUN
Parameters
uuid_or_uuids_list str | Sequence[str]
LUN UUID or list of LUN UUIDs
Returns
dict[str, object]
API response.
safe_delete
Delete one or more LUNs, awaiting for complete deletion before returning.
Internal API
SYNO.Core.ISCSI.LUN
Parameters
uuid_or_uuids_list str | Sequence[str]
LUN UUID or list of LUN UUIDs
min_request_delay float
Minimum delay (in seconds) between two calls to LUN.list() when checking for complete deletion.
Returns
dict[str, object]
API response.
list
List available LUNs.
Internal API
SYNO.Core.ISCSI.LUN
Parameters
types List[str]
Type of LUNS to retrieve.
Defaults to [ "BLOCK", "FILE", "THIN", "ADV", "SINK", "CINDER", "CINDER_BLUN", "CINDER_BLUN_THICK", "BLUN", "BLUN_THICK", "BLUN_SINK", "BLUN_THICK_SINK" ].
Possible values:
"BLOCK""FILE""THIN""ADV""SINK""CINDER""CINDER_BLUN""CINDER_BLUN_THICK""BLUN""BLUN_THICK""BLUN_SINK""BLUN_THICK_SINK"
additional_info List[str]
Additional LUN information to include in the response. Specify [] to get only basic information.
Defaults to [ "is_action_locked", "is_mapped", "extent_size", "allocated_size", "status", "allow_bkpobj", "flashcache_status", "family_config", "snapshot_info" ].
Possible values:
"is_action_locked""is_mapped""extent_size""allocated_size""status""allow_bkpobj""flashcache_status""family_config""snapshot_info"
location str
Filter by location.
Returns
dict[str, object]
API response containing LUN list.
Example return
Click to expand
{
"data": {
"luns": [
{
"allocated_size": 0,
"block_size": 512,
"create_from": "",
"description": "",
"dev_attribs": [
{
"dev_attrib": "emulate_3pc",
"enable": 1
},
{
"dev_attrib": "emulate_tpws",
"enable": 1
},
{
"dev_attrib": "emulate_caw",
"enable": 1
},
{
"dev_attrib": "emulate_tpu",
"enable": 1
},
{
"dev_attrib": "emulate_fua_write",
"enable": 0
},
{
"dev_attrib": "emulate_sync_cache",
"enable": 0
},
{
"dev_attrib": "can_snapshot",
"enable": 1
}
],
"dev_attribs_bitmap": 31,
"dev_config": "",
"dev_qos": {
"dev_limit": 0,
"dev_reservation": 0,
"dev_weight": 0,
"iops_enable": 0
},
"direct_io_pattern": 0,
"extent_size": 0,
"family_config": {
"parent_lun_name": "",
"parent_lun_uuid": "",
"parent_snapshot_time": 0,
"parent_snapshot_uuid": ""
},
"flashcache_id": -1,
"flashcache_status": "no_cache",
"is_action_locked": false,
"is_mapped": true,
"location": "/volume2",
"lun_id": 6,
"name": "LUN-1",
"restored_time": 0,
"retention": null,
"scheduled_task": [
{
"general": {
"snap_rotate": true,
"snap_type": "app",
"task_enabled": false,
"task_name": "Task LUN-1",
"tid": -1,
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"schedule": {
"date": "2025/3/24",
"date_type": 0,
"hour": 0,
"last_work_hour": 0,
"min": 0,
"monthly_week": [],
"next_trigger_time": "",
"repeat": 0,
"repeat_hour": 0,
"repeat_hour_store_config": null,
"repeat_min": 0,
"repeat_min_store_config": null,
"week_name": "0,1,2,3,4,5,6"
}
}
],
"size": 1073741824,
"snapshots": [
{
"create_time": 1742739365,
"description": "test",
"is_app_consistent": false,
"is_user_locked": true,
"mapped_size": 0,
"name": "SnapShot-1",
"parent_lun_id": 6,
"parent_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"root_path": "/volume2",
"snapshot_id": 1,
"snapshot_time": 1742739365,
"status": {
"progress": {
"percent": -1,
"step": "waiting"
},
"type": "Healthy"
},
"taken_by": "user",
"total_size": 1073741824,
"type": 2,
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"version": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
],
"status": "normal",
"type": 263,
"type_str": "BLUN",
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"vpd_unit_sn": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
]
},
"success": true
}
get
Get a specific LUN.
Internal API
SYNO.Core.ISCSI.LUN
Parameters
uuid str
LUN UUID.
additional_info List[str]
Additional LUN information to include in the response. Specify [] to get only basic information.
Defaults to [ "is_action_locked", "is_mapped", "extent_size", "allocated_size", "status", "import_status", "sync_progress", "is_vhost_mapped", "is_bound", "whitelist", "flashcache_status", "family_config" ].
Possible values:
"is_action_locked""is_mapped""extent_size""allocated_size""status""import_status""sync_progress""is_vhost_mapped""is_bound""whitelist""flashcache_status""family_config"
Returns
dict[str, object]
API response.
Example return
Click to expand
{
'data': {
'import_done': 0,
'import_errno': 18990593,
'import_total': 0,
'lun': {
'allocated_size': 4294967296,
'block_size': 512,
'create_from': '',
'description': '',
'dev_attribs': [
{'dev_attrib': 'emulate_3pc', 'enable': 0},
{'dev_attrib': 'emulate_tpws', 'enable': 0},
{'dev_attrib': 'emulate_caw', 'enable': 1},
{'dev_attrib': 'emulate_tpu', 'enable': 0},
{'dev_attrib': 'emulate_fua_write', 'enable': 0},
{'dev_attrib': 'emulate_sync_cache', 'enable': 0},
{'dev_attrib': 'can_snapshot', 'enable': 0}
],
'dev_attribs_bitmap': 2,
'dev_config': '',
'dev_qos': {
'dev_limit': 0,
'dev_reservation': 0,
'dev_weight': 0,
'iops_enable': 0
},
'direct_io_pattern': 0,
'extent_size': 0,
'family_config': {
'parent_lun_name': '',
'parent_lun_uuid': '',
'parent_snapshot_time': 0,
'parent_snapshot_uuid': ''
},
'flashcache_id': -1,
'flashcache_status': 'no_cache',
'is_action_locked': False,
'is_bound': False,
'is_mapped': True,
'is_vhost_mapped': False,
'location': '/volume2',
'lun_id': 1,
'max_snapshot_count': 256,
'name': 'xxxxx',
'restored_time': 0,
'size': 4294967296,
'status': 'normal',
'sync_done': 0,
'sync_errno': 0,
'sync_total': 0,
'type': 259,
'type_str': 'BLUN_THICK',
'uuid': 'f699bc85-3be4-4eb0-9332-020b47143169',
'vpd_unit_sn': 'f699bc85-3be4-4eb0-9332-020b47143169'
},
'sync_done': 0,
'sync_errno': 0,
'sync_total': 0,
'whitelist': ['0.0.0.0', '0.0.0.0']
},
'success': True
}
set
Update LUN properties.
Internal API
SYNO.Core.ISCSI.LUN
Parameters
uuid str
LUN UUID.
new_name str
Rename LUN.
new_size int or str
Resize LUN (may be unsupported in many cases).
new_type {"BLOCK","FILE","THIN","ADV","BLUN","BLUN_THICK"}
Change type (may be unsupported in many cases).
new_location str
Move LUN location (may be unsupported in many cases).
emulate_caw bool
Enable SCSI COMPARE AND WRITE (CAW) support.
Allows atomic compare-and-write operations, typically used
by clustered filesystems or applications requiring
conditional block updates. When enabled, the LUN reports
support for the CAW command to the initiator.
emulate_3pc bool
Enable SCSI Third-Party Copy (XCOPY) support.
Allows block-level offloaded copy operations between
devices without transferring data through the initiator.
Used by hypervisors and storage-aware backup systems.
emulate_tpu bool
Enable SCSI UNMAP support (Thin Provisioning UNMAP).
Allows the initiator to explicitly deallocate logical
block ranges that are no longer in use (e.g. filesystem
discard/TRIM). Required for proper space reclamation
on thin-provisioned LUNs.
emulate_tpws bool
Enable SCSI WRITE SAME support with thin provisioning
semantics (Thin Provisioning WRITE SAME).
Allows large zero-write operations that may be interpreted
by the storage backend as deallocation hints. Often used
as an alternative or complement to UNMAP for space
reclamation.
emulate_fua_write bool
Enable handling of the SCSI Force Unit Access (FUA) bit
on write commands (DSM 7+).
When enabled, write commands marked with FUA are forced
to stable storage before completion is reported. Disabling
this may improve performance but can weaken durability
guarantees.
emulate_sync_cache bool
Enable support for the SCSI SYNCHRONIZE CACHE command
(DSM 7+).
When enabled, explicit cache flush requests from the
initiator are honored, ensuring that buffered writes are
committed to stable storage. Disabling this may increase
performance at the cost of reduced crash-consistency
guarantees.
can_snapshot bool
Enable snapshot capability for the LUN.
When set, the LUN is eligible for snapshot creation and
snapshot-based operations (e.g. cloning, replication).
Valid only for thin-provisioned LUN types.
Returns
dict[str, object]
API response (e.g. {'success': True}).
clone
Clone a LUN.
Internal API
SYNO.Core.ISCSI.LUN
Parameters
src_lun_uuid str
Source LUN UUID.
dst_lun_name str
Destination LUN name.
clone_type str
Clone type.
dst_location str
Destination location.
dst_node_uuid str
Destination node UUID (for remote scenarios).
dst_address str
Destination address (for remote scenarios).
dst_port int or str
Destination port (for remote scenarios).
is_data_encrypted bool
Whether data is encrypted in transit ?
is_soft_feas_ignored bool
Ignore "soft-feasibility"
is_data_clone bool
Unknown flag
Returns
dict[str, object]
API response.
stop_clone
Stop an in-progress clone operation.
Internal API
SYNO.Core.ISCSI.LUN
Parameters
src_lun_uuid str
Source LUN UUID.
Returns
dict[str, object]
API response.
map_target
Map a LUN to one or more targets.
Internal API
SYNO.Core.ISCSI.LUN
Parameters
uuid str
LUN UUID.
target_ids (int or str) or Sequence[int or str]
Target ID or IDs.
Returns
dict[str, object]
API response.
unmap_target
Unmap a LUN from one or more targets.
Internal API
SYNO.Core.ISCSI.LUN
Parameters
uuid str
LUN UUID.
target_ids (int or str) or Sequence[int or str]
Target ID or IDs.
Returns
dict[str, object]
API response.
Target
Overview
API wrapper for Synology iSCSI Target management. This class targets the SYNO.Core.ISCSI.Target WebAPI.
Methods
- Getters :
- List targets
- Get target details
- Setters :
- Update target properties (name/iqn/session limits/checksums/auth)
- Actions :
- Create / delete
- Enable / disable
- Map / unmap LUNs
Methods
create
Create a target.
Internal API
SYNO.Core.ISCSI.Target
Parameters
name str
Target name.
iqn str
ISCSI Qualified Name.
auth_type {0,1,2}
Authentication type:
0-> none (default)1-> single CHAP2-> mutual CHAP
max_sessions int
Maximum sessions (use 0 for unlimited on some systems).
user str
CHAP username (client). Requires auth_type >= 1.
password str
CHAP password (client). Requires auth_type >= 1.
mutual_user str
Mutual CHAP username (server). Requires auth_type == 2.
mutual_password str
Mutual CHAP password (server). Requires auth_type == 2.
Returns
dict[str, object]
API response.
Example return
Click to expand
{
'data': {
'target_id': 3
},
'success': True
}
delete
Delete a target.
Internal API
SYNO.Core.ISCSI.Target
Parameters
target_id int | str
Integer id of iSCSI target.
Returns
dict[str, object]
API response.
Example return
Click to expand
{
'success': True
}
list
List available iSCSI targets.
Internal API
SYNO.Core.ISCSI.Target
Parameters
additional_info List[str]
Additional information to include in the response. Specify [] to get only basic information.
Defaults to ["mapped_lun","acls","connected_sessions","status"]
lun_uuid str
Filter targets mapped to LUN with provided uuid.
Returns
dict[str, object]
API response containing iSCSI target list.
Example return
Click to expand
{
'data': {
'targets': [
{
'auth_type': 0,
'connected_sessions': [],
'has_data_checksum': False,
'has_header_checksum': False,
'iqn': 'iqn.2025-01.com.synology:raspberry-pi',
'is_default_target': False,
'is_enabled': True,
'mapped_luns': [
{
'lun_uuid': 'f699bc85-3be4-4eb0-9332-020b47143169',
'mapping_index': 1
}
],
'mapping_index': -1,
'max_recv_seg_bytes': 262144,
'max_send_seg_bytes': 262144,
'max_sessions': 1,
'mutual_password': '',
'mutual_user': '',
'name': 'raspberry-pi',
'network_portals': [
{'interface_name': 'all', 'ip': '', 'port': 3260}
],
'password': '',
'status': 'online',
'target_id': 1,
'user': ''
},
{
'auth_type': 0,
'connected_sessions': [],
'has_data_checksum': False,
'has_header_checksum': False,
'iqn': 'iqn.2000-01.com.synology:xxx.default-target.xxxxxxx',
'is_default_target': True,
'is_enabled': True,
'mapped_luns': [],
'mapping_index': -1,
'max_recv_seg_bytes': 262144,
'max_send_seg_bytes': 262144,
'max_sessions': 1,
'mutual_password': '',
'mutual_user': '',
'name': 'Synology iSCSI Target',
'network_portals': [
{'interface_name': 'all', 'ip': '', 'port': 3260}
],
'password': '',
'status': 'online',
'target_id': 2,
'user': ''
}
]
},
'success': True
}
get
Get information on iSCSI target with id target_id.
Internal API
SYNO.Core.ISCSI.Target
Parameters
target_id int | str
Integer id of iSCSI target.
additional_info List[str]
Additional information to include in the response. Specify [] to get only basic information.
Defaults to ["mapped_lun","acls","connected_sessions","status"]
Returns
dict[str, object]
API response containing iSCSI target info.
Example return
Click to expand
{
'data': {
'target': {
'auth_type': 0,
'connected_sessions': [],
'has_data_checksum': False,
'has_header_checksum': False,
'iqn': 'iqn.2000-01.com.synology:xxx.default-target.xxxxxxx',
'is_default_target': True,
'is_enabled': True,
'mapped_luns': [],
'mapping_index': 0,
'max_recv_seg_bytes': 262144,
'max_send_seg_bytes': 262144,
'max_sessions': 1,
'mutual_password': '',
'mutual_user': '',
'name': 'Synology iSCSI Target',
'network_portals': [{'interface_name': 'all', 'ip': '', 'port': 3260}],
'password': '',
'status': 'online',
'target_id': 2,
'user': ''
}
},
'success': True
}
set
Update target properties.
Internal API
SYNO.Core.ISCSI.Target
Parameters
target_id int | str
Integer id of iSCSI target.
new_name str
New target name.
new_iqn str
New target iqn.
max_sessions int
Maximum sessions (use 0 for unlimited on some systems).
auth_type {0,1,2}
New authentication type:
0-> none1-> single CHAP2-> mutual CHAP
user str
CHAP username (client). Requires auth_type >= 1.
password str
CHAP password (client). Requires auth_type >= 1.
mutual_user str
Mutual CHAP username (server). Requires auth_type == 2.
mutual_password str
Mutual CHAP password (server). Requires auth_type == 2.
has_header_checksum bool
Enable CRC (cyclic redundancy check) header digest. Typically redundant in Ethernet + TCP settings.
has_data_checksum bool
Enable CRC (cyclic redundancy check) data digest. Typically redundant in Ethernet + TCP settings.
max_recv_seg_bytes int
Maximum receive segment bytes. Available values in Diskstation GUI are 4096, 8192, 65536, 262144 (default).
max_send_seg_bytes int
Maximum send segment bytes. Available values in Diskstation GUI are 4096, 8192, 65536, 262144 (default).
Returns
dict[str, object]
API response.
Example return
Click to expand
{
'success': True
}
enable
Enable a target.
Internal API
SYNO.Core.ISCSI.Target
Parameters
target_id int | str
Integer id of iSCSI target.
Returns
dict[str, object]
API response.
disable
Disable a target.
Internal API
SYNO.Core.ISCSI.Target
Parameters
target_id int | str
Integer id of iSCSI target.
Returns
dict[str, object]
API response.
map_lun
Map one or more LUNs to a target.
Internal API
SYNO.Core.ISCSI.Target
Parameters
target_id int | str
Integer id of iSCSI target.
lun_uuid_or_uuids_list str | Sequence[str]
LUN UUID or list of LUN UUIDs
Returns
dict[str, object]
API response.
unmap_lun
Unmap one or more LUNs from a target.
Internal API
SYNO.Core.ISCSI.Target
Parameters
target_id int | str
Integer id of iSCSI target.
lun_uuid_or_uuids_list str | Sequence[str]
LUN UUID or list of LUN UUIDs
Returns
dict[str, object]
API response.
Replication
Overview
API wrapper for SYNO.Core.ISCSI.Replication (iSCSI LUN replication).
Read-only coverage of LUN replication tasks.
Methods
list
List iSCSI LUN replication tasks (read-only).
Internal API
SYNO.Core.ISCSI.Replication
Returns
dict[str, object] | str
API response with the replication task list.
get
Get iSCSI LUN replication task details (read-only).
Internal API
SYNO.Core.ISCSI.Replication
Parameters
target_id Optional[int]
Replication target ID.
lun_uuid Optional[str]
LUN UUID.
Returns
dict[str, object] | str
API response with the replication task details.
VMware
Overview
API wrapper for SYNO.Core.ISCSI.VMware (VMware VAAI integration).
Read-only coverage of VMware storage integration entries.
Methods
list
List VMware storage integration entries (read-only).
Internal API
SYNO.Core.ISCSI.VMware
Returns
dict[str, object] | str
API response with the VMware integration entry list.
get
Get VMware storage integration entry details (read-only).
Internal API
SYNO.Core.ISCSI.VMware
Parameters
target_id Optional[int]
VMware integration target ID.
Returns
dict[str, object] | str
API response with the VMware integration entry details.