Core iscsi

[Sartohanix]

This is an implementation of the basic methods for the APIs SYNO.Core.ISCSI.LUN and SYNO.Core.ISCSI.Target ; dedicated to iSCSI LUNs & targets management.

The implementation was mostly guided by the usage message of /var/packages/ScsiTarget/target/bin/synoiscsiwebapi and reverse-engineering of the requests triggered by the Diskstation GUI.

I've implemented specific errors/exceptions for LUN- and Target-related errors, with a few commonly occurring error codes.

Summary of implemented methods, included in new file synology_api/core_iscsi.py

• Class LUN(base_api.BaseApi):
  • create
  • delete
  • safe_delete: a higher-level wrapper, waiting for complete LUN deletion.
  • list
  • get
  • set
  • clone
  • stop_clone
  • map_target
  • unmap_target
• Class Target(base_api.BaseApi):
  • create
  • delete
  • list
  • get
  • set
  • enable
  • disable
  • map_lun
  • unmap_lun

All basic methods & features have been tested.

Note that I've made a (single) modification in the existing code, related to the SynoBaseException class. The error message was not previously passed to the parent (Exception) constructor, yielding empty exception messages in the interpreter.

I'll spend some more time adding examples in the main classes' docstrings. A few are already present for LUN(), e.g.

from synology_api.core_iscsi import LUN

## List LUNs

lun_api = LUN('IP', 'PORT', 'USER', 'PASSWORD')
lun_list = lun_api.list()

print(lun_list['data']['luns'])

## Create a new LUN

my_lun = lun_api.create(
    'my-LUN-1234',   # Special characters other than "-" trigger API errors upon creation
    'THIN',          # Non-legacy and non-internal LUN types include: 'FILE', 'THIN' (ext4 and btrfs) ; 'BLUN', 'BLUN_THICK' (btrfs)
    '/volume1',      # Note the leading '/'
    1024**3,         # Size in bytes
    description="Project XYZ"
)

print(my_lun)
# -> {'data': {'lun_id': 7, 'uuid': 'ac36dabc-6e23-40e0-8956-c8bc8a00397e'}, 'success': True}

## Get information for a given LUN (e.g. the one just created)
uuid = my_lun['data']['uuid']
lun_info = lun_api.get(uuid)

print(lun_info['data'])  # Includes import & sync information
print(lun_info['data']['lun'])

## Trigger LUN deletion

lun_del_response = lun_api.delete(uuid)   # Single LUN deletion
multiple_lun_del_response = lun_api.delete([uuid1, uuid2, ...])   # Multiple LUN deletion

# Wait until complete deletion
safe_lun_del_response = lun_api.safe_delete(uuid)

## Set new characteristics for a given LUN (when allowed by context)

uuid = my_lun['data']['uuid']

lun_api.set(uuid, new_name='my-LUN-4321', new_type='BLUN')

## Clone LUN

uuid = my_lun['data']['uuid']

print(
    lun_api.clone(uuid, 'my-cloned-LUN', dst_location='/volume2')
)
# -> {'data': {'dst_lun_uuid': '58407cf0-a5d9-480d-98cc-53d8ac691f96'}, 'success': True}

[N4S4]

it is not generating docs due to the sidebar position? not sure adding @joeperpetua

[joeperpetua]

The sidebar position is computed from the docs_status file.

Gotta add an entry there for the docs Metadata to be generated correctly.

[Sartohanix]

The sidebar position is computed from the docs_status file.

Gotta add an entry there for the docs Metadata to be generated correctly.

Sorry for the omission. Should be fine now

[joeperpetua]

FYI your approach of using an internal field for the API name will not update the supported APIs docs.

The docs parser is looking for api_name = '...' within the class methods to generate the supported APIs.

You may want to modify your request approach or update the parser to handle the current one.

[Sartohanix]

Now ready to merge. Internal APIs are properly listed in the docs, based on #334's new _API_NAME = ... class-scope attribute.