icloudpd中的各种参数
MANDATORY ENVIRONMENT VARIABLES
apple_id: This is the Apple ID that wil lbe used when downloading files.
DEFAULT ENVIRONMENT VARIABLES
user: This is name of the user account that you wish to create within the container. This can be anything you choose, but ideally you would set this to match the name of the user on the host system for which you want to download files for. This user will be set as the owner of all downloaded files. If this variable is not set, it will default to ‘user’.
user_id: This is the User ID number of the above user account. This can be any number that isn’t already in use. Ideally, you should set this to be the same ID number as the user’s ID on the host system. This will avoid permissions issues if syncing to your host’s home directory. If this variable is not set, it will default to ‘1000’.
group: This is name of the group account that you wish to create within the container. This can be anything you choose, but ideally you would set this to match the name of the user’s primary group on the host system. This This group will be set as the group for all downloaded files. If this variable is not set, it will default to ‘group’.
group_id: This is the Group ID number of the above group. This can be any number that isn’t already in use. Ideally, you should set this to be the same Group ID number as the user’s primary group on the host system. If this variable is not set, it will default to ‘1000’.
force_gid: If this variable is set it will allow the group to be created with a pre-existing group id. This may be handy if your group id clashes with a system group insude the docker container, however, if may have undesired permissions issues. Please use with caution.
TZ: This is the local timezone and is required to calculate timestamps. If this variable is not set, it will default to Coordinated Universal Time ‘UTC’.
download_path: This is the directory to which files will be downloaded from iCloud. If this variable is not set, it will default to “/home/${user}/iCloud”.
synchronisation_interval: This is the number of seconds between synchronisations. It can be set to the following periods: 43200 (12hrs), 86400 (24hrs), 129600 (36hrs), 172800 (48hrs) and 604800 (7 days). If this variable is not set to one of these values, it will default to 86400 seconds. Be careful if setting a short synchronisation period. Apple have a tendency to throttle connections that are hitting their server too often. I find that every 24hrs is fine. My phone will upload files to the cloud immediately, so if I lose my phone the photos I’ve taken that day will still be safe in the cloud, and the container will download those photos when it runs in the evening.
synchronisation_delay: This is the number of minutes to delay the first synchronisation. This is so that you can stagger the synchronisations of multiple containers. If this value is not set. It will default to 0.
notification_days: When your cookie is nearing expiration, this is the number of days in advance it should notify you. This will default to 7 days if not specified so you will receive a single notification in the 7 days running up to cookie expiration.
authentication_type: This is the type of authentication that is enabled on your iCloud account. Valid values are ‘2FA’ if you have two factor authentication enabled or ‘Web’ if you do not. If ‘Web’ is specified, then cookie generation is not required. If this variable is not set, it will default to ‘2FA’.
directory_permissions: This specifies the permissions to set on the directories in your download destination. If this variable is not set, it will default to 750.
file_permissions: This specifies the permissions to set on the files in your download destination. If this variable is not set, it will default to 640.
folder_structure: This specifies the folder structure to use in your download destination directory. If this variable is not set, it will set {:%Y/%m/%d} as the default. Use none to download to a flat file structure.
skip_check: This variable specifies whether the download check is skipped. If this is set to True the script will process a download run each time it is run. If this variable is not set, it will default to False.
download_notifications: This variable specifies whether notifications with a short summary should be sent for file downloads. If this variable is not set, it will default to True.
delete_notifications: This variable specifies whether notifications with a short summary should be sent for file deletions. If this variable is not set, it will default to True.
set_exif_datetime: Write the DateTimeOriginal exif tag from file creation date. If this variable is not set, it will default to False.
auto_delete: Scans the “Recently Deleted” folder and deletes any files found in there. (If you restore the photo in iCloud, it will be downloaded again). If this variable is not set, it will default to False.
photo_size: Image size to download. Can be set to original, medium or thumb. If this variable is not set, it will default to original.
skip_live_photos: If this is set, it will skip downloading live photos. If this variable is not set, it will default to False.
live_photo_size: Live photo file size to download. Can be set to original, medium or thumb. If skip_live_photos is set, this setting is redundant. If this variable is not set, it will default to original.
skip_videos: If this is set, it will skip downloading videos. If this variable is not set, it will default to False.
recent_only: Set this variable to an integer number to only download this many recently added photos. If this variable is not set, it will default to downloading all photos.
until_found: Set this variable to an integer number to only download the most recently added photos, until n number of previously downloaded consecutive photos are found. If this variable is not set, it will default to downloading all photos.
OPTIONAL ENVIRONMENT VARIABLES
command_line_options: This is for additional command line options you want to pass to the icloudpd application. The list of options for icloudpd can be found HERE.
convert_heic_to_jpeg: If this variable is set, it will convert any HEIC files it downloads to JPEG, while also retaining the original.
jpeg_quality: If HEIC to JPEG conversion is enabled, this variable will let you set the quality of the converted file by specifying a number from 0 (lowest quality) to 100 (highest quality) If convert_heic_to_jpeg is set, and this variable isn’t, it will default to 90.
icloud_china: If this variable is set, it will use icloud.com.cm instead of icloud.com as the download source.
NOTIFICATION CONFIGURATION VARIABLES
notification_type: This specifies the method that is used to send notifications. Currently, there are six options available Prowl, Pushover, Telegram, Webhook, Dingtalk and Discord. When the two factor authentication cookie is within 7 days (default) of expiry, a notification will be sent upon synchronisation. No more than a single notification will be sent within a 24 hour period unless the container is restarted. This does not include the notification that is sent each time the container is started.
notification_title: This allows you to change the title which is sent on the notifications. If this variable is not set, it will default to boredazfcuk/iCloudPD.
prowl_api_key: If the notification_type is set to ‘Prowl’ this is mandatory. This is the API key for your account as generated by the Prowl website.
pushover_user: If the notification_type is set to ‘Pushover’ this is mandatory. This is the user name that was chose when creating the Pushover account.
pushover_token: If the notification_type is set to ‘Pushover’ this is mandatory. This is the access token your account as generated by the Pushover website.
telegram_token: If the notification_type is set to ‘Telegram’ this is mandatory. This is the token that was assigned to your account by The Botfather.
telegram_chat_id: If the notification_type is set to ‘Telegram’ then this is the chat_id for your Telegram bot. If the bot is a standard user that messages you, the chat ID will be a positive integer number. If the bot is a member of a group, and sends messages to the group, the chat ID will be prefixed with a hyphen ‘-‘ character.
webhook_server: If the notification_type is set to ‘Webhook’ then this is the name of the server to connect to when sending webhook notifications.
webhook_port: If the notification_type is set to ‘Webhook’ then this is the port number to use when connecting to the webhook server. If this is not set, it will default to 8123.
webhook_path: If the notification_type is set to ‘Webhook’ then this is the path to use when connectiong to the webhook server. The path must start and end with a forward slash character. If this is not set, it will default to /api/webhook/.
webhook_id: If the notification_type is set to ‘Webhook’ then this is the Webhook ID to use.
webhook_https: If this is set to ‘True then the Webhoot notification URL will use HTTPS, otherwise it will default to HTTP.
webhook_body: Adapt to different services. Homeassistant uses “data” in the body of the webhook request, Discord uses “content”, IFTTT uses “value1”, etc.. Defaults to “data”.
dingtalk_token: If the notification_type is set to ‘Dingtalk’ then this is the access token generated by the Dingtalk application. In the Dingtalk application, go to ‘Security Settings’, select ‘Custom Keywords’ and set to to the same value as notification_title.
discord_id: This is the first half of the URL generated by Discord’s webhook integration. It will be all numbers. Do not include any /
discord_token: This is the second half of the URL generated by Discords webhook integration. Do no include any /
VOLUME CONFIGURATION
This container requires a named volume mapped to /config. This is where is stores the authentication cookie. Without it, it will lose the cookie information each time the container is recreated. It will download the photos to the “/home/${user}/iCloud” photos directory. You need to create a bind mount into the container at this point.
FAILSAFE FEATURE
I have added a failsafe feature to this container so that it doesn’t make any changes to the filesystem unless it can verify the volume it is writing to is mounted correctly. The container will look for a file called “/home/${user}/iCloud/.mounted” (please note the capitalisation of iCloud) in the download destination directory inside the container. If this file is not present, it will not download anything from iCloud. This way, if underlying disk/volume/whatever gets unmounted, sync will not occur and this prevents the script from filling up the root volume of the host. This file MUST be created manually and sync will not start without it.
CREATING A CONTAINER
First off, create a dedicated network for your iCloudPD conter(s) as this overcomes some DNS and routing issues may occur if you use the legacy default network bridge that Docker creates. In this example, I’ve have told it to use the IP address subnet 192.168.115.1 – 192.168.115.254 and configured the gateway to be 192.168.115.254. You can use any subnet that :
docker network create \
--driver=bridge \
--subnet=192.168.115.0/24 \
--gateway=192.168.115.254 \
--opt com.docker.network.bridge.name=icloudpd_br0 \
icloudpd_bridge
Then create the container like this, connecting it to the new icloudpd network bridge:
docker create \
--name <Contrainer Name> \
--hostname <Hostname of container> \
--network icloudpd_bridge \
--restart=always \
--env user=<User Name> \
--env user_id=<User ID> \
--env group=<Group Name> \
--env group_id=<Group ID> \
--env apple_id="<Apple ID e-mail address>" \
--env authentication_type=<2FA or Web> \
--env synchronisation_interval=<Include this if you wish to override the default interval of 24hrs> \
--env notification_type=<Choice of Prowl/Pushover/Webhook/Telegram/Dingtalk> \
--env notification_days=<Number of days for which to send cookie expiry notifications> \
--env TZ=<The local time zone> \
--volume <Named volume which is mapped to /config> \
--volume <Bind mount to the destination folder on the host> \
boredazfcuk/icloudpd
So an example of a true command would look something like this:
docker create \
--name iCloudPD-boredazfcuk \
--hostname icloudpd_boredazfcuk \
--network icloudpd_bridge \
--restart=always \
--env user=boredazfcuk \
--env user_id=1000 \
--env group=admins \
--env group_id=1010 \
--env apple_id=thisisnotmy@email.com \
--env apple_password="neitheristhismypassword" \
--env authentication_type=2FA \
--env notification_type=Telegram \
--env telegram_token=123654 \
--env telegram_chat_id=456321 \
--env folder_structure={:%Y} \
--env auto_delete=True \
--env notification_days=14 \
--env synchronisation_interval=21600 \
--env TZ=Europe/London \
--volume icloudpd_boredazfcuk_config:/config \
--volume /home/boredazfcuk/iCloud:/home/boredazfcuk/iCloud \
boredazfcuk/icloudpd
CONFIGURING A PASSWORD
Once the container has been created, you should connect to it and run /usr/local/bin/sync-icloud.sh --Initialise. This will then take you through the process of adding your password to the container’s keyring. It will also take you through generating a cookie that will allow the container to download the photos…
If you launch a container without initialising it first, you will receive an error message similar to this:
ERROR Keyring file /config/python_keyring/keyring_pass.cfg does not exist.
INFO - Please add the your password to the system keyring using the --Initialise script command line option.
INFO - Syntax: docker exec -it <container name> sync-icloud.sh --Initialise
INFO - Example: docker exec -it icloudpd sync-icloud.sh --Initialise
INFO Restarting in 5 minutes...
As per the error, the container needs to be initialised by using the –Initialise command line option. With the first container still running, connect to it and launch the initialisation process by running the following at the terminal prompt (assuming the container name is ‘icloudpd’):
docker exec -it icloudpd sync-icloud.sh --Initialise
You will then be asked to log in to icloud.com, with your current Apple ID and password, and will be prompted to enter a two factor authentication code which will be sent via SMS. Once that is confirmed, the password will be added to the keyring.
If you do not have an authentication cookie, and you have two factor authentication enabled on your account, you will be taken to the cookie generation process immediately after.
TWO FACTOR AUTHENTICATION
If your Apple ID account has two factor authentication enabled, you will see that the container waits for a two factor authentication cookie to be created:
ERROR Cookie does not exist."
INFO - Please create your cookie using the --Initialise script command line option."
INFO - Syntax: docker exec -it <container name> sync-icloud.sh --Initialise"
INFO - Example: docker exec -it icloudpd sync-icloud.sh --Initialise"
INFO Restarting in 5 minutes..."
Without this cookie, synchronisation cannot be started.
As per the error, the container needs to be initialised by using the –Initialise command line option. With the first container still running, connect to it and launch the initialisation process by running the following at the terminal prompt (assuming the container name is ‘icloudpd’):
docker exec -it icloudpd sync-icloud.sh --Initialise
After that, the script will log into the icloud.com website and save the 2FA cookie. Your iDevice will ask you if you want to allow or deny the login. When you allow the login, you will be give a 6-digit approval code. Enter the approval code when prompted.
