MirrorMcsmcdR

中文 | English

An advance plugin for MCDR that can control mirror servers and synchronize files in various ways.

Features

• The plugin supports controlling mirror servers through MCSManager, and can also control mirror servers directly through the terminal or RCON without relying on MCSM (v1.3.0+)
  • MCSM Control: Supports MCSM-v9.9.0 MCSM-v10.2.1+
  • Terminal or RCON Control: Supports Windows Linux systems
• Comprehensive multi-mirror server control operations: obtaining running status, starting server, stoping server, force termination and synchronization
• Hash-based file synchronization, only synchronizes files that are different between the mirror server and the source server
• Highly customizable and friendly configuration file, only the changed values need to be written when configuring multiple mirror servers

[Note] This plugin does not provide server creation or management functionality. Please use this plugin after the mirror server is created and the MCSManager instance is created. Similarly, this plugin does not provide prompts for the successful start or stop of the mirror server, and it is recommended to use it in conjunction with plugins such as vchat.

Dependencies

Python

xxhash>=3

System

When using the terminal to start the mirror server and the system is Linux: screen is required

Commands

The default command prefix is !!mirror. When controlling multiple mirror servers, the command prefix will be used to distinguish, see Configuration File

!!mirror Displays command help

!!mirror help Displays command help

!!mirror status Gets the running status of the mirror server instance, the status is unknown/stopped/stopping/starting/running

!!mirror start Starts the mirror server instance

!!mirror stop Stops the mirror server instance

!!mirror kill Forcefully terminates the mirror server instance

!!mirror sync Synchronizes files

!!mirror confirm Confirms the operation of a certain command

!!mirror reload Hot reloads the configuration file for the specified mirror server

Configuration File

This configuration file is quite long. We recommend that you read the Quick Start to complete the preliminary configuration. If you need to find an explanation for a specific configuration item, you can read the following.

The configuration file supported hot reloading in v1.1.0, and at the same time added a more comprehensive attribute completion function. When a new version of the configuration file adds an option, the plugin will automatically fill in the default value in your old configuration file, without the need for manual addition.

{
    "!!mirror": {
        "mcsm": {/* MCSManager configuration */},
        "terminal": {/* Configuration for starting the mirror server terminal through the command line */},
        "rcon": {/* RCON configuration */},
        "sync": {/* Save synchronization configuration */},
        "command": {
            "permission": {/* Command permission configuration */},
            "action": {/* Command behavior configuration */}
        },
        "display": {/* Display configuration */}
    }
}

"!!mirror"

Under this parameter, all configurations for the mirror server are configured, and this parameter is also the command prefix for controlling the mirror server.

To add a new mirror server, such as controlling mirror server 2 through !!mirror2, simply add another "!!mirror2" in the configuration file.

The parameters set for the first mirror server in the configuration file will also be set as the default configuration. In the subsequent mirror server configuration files, only the changed parameter values need to be written.

Example

Mirror server 1 is !!mirror, which is also the default configuration file for other mirror servers, then put !!mirror in the first place in the configuration file.

Control mirror server 2 through !!mirror2, and set the instance id of !!mirror2 to abc123, change the server name of !!mirror2 to Mirror2

{
    "!!mirror": {
        // ...
    },
    "!!mirror2": {
        "mcsm": {
            "uuid": "abc123"
        },
        "display": {
            "server_name": "Mirror2"
        }
    }
}

In it, the parameters not set in !!mirror2 will automatically inherit from the first set !!mirror, for example, !!mirror2 did not set the url of mcsm, then it will inherit from the url of mcsm in !!mirror, that is "http://127.0.0.1:23333/"

For a complete example, see Multi-mirror Server Configuration File Example

mcsm: MCSManager Configuration

If you have any questions about this configuration section, please refer to the MCSManager Documentation

"mcsm": {
    "enable": false,
    "url": "http://127.0.0.1:23333/", 
    "uuid": null,
    "remote_uuid": null,
    "apikey": null
}

After enabling MCSM, the terminal and RCON will be disabled.

enable bool

• Whether to enable MCSM. You need to set this option to true after completing the configuration of this section.

url str

• The access address of the MCSManager panel, that is, the address for requesting the API.

uuid str

• The ID of the server instance, that is, the UID displayed by the instance.

remote_uuid str

• The ID of the remote node, that is, the GID displayed by the instance.

apikey str

• The key required to call the API interface, which can usually be viewed in the user interface.

terminal: Configuration for starting the mirror server terminal through the command line

"terminal": {
    "enable": false,
    "launch_path": "./Mirror",
    "launch_command": "python -m mcdreforged",
    "port": null,
    "terminal_name": "Mirror",
    "regex_strict": false,
    "system": null
}

Under Windows system, the plugin will create a new terminal to run the mirror server; under Linux system, the plugin will create a new screen to run the mirror server. After the mirror server stops, the terminal or screen will be closed automatically.

If you cannot start the mirror server with this command, try the following steps for inspection. Among them, terminal_name launch_command are the values of the corresponding keys in the configuration file.

1. Execute launch_command under launch_path and confirm that it can start the mirror server successfully
2. Linux users check if screen is installed, Windows users check if python command can start Python successfully in the terminal
3. If the above two suggestions cannot be resolved, then execute the complete command corresponding to the system in the root directory of the current server's MCDR, and check the command echo
   • Linux cd "{launch_path}"&&screen -dmS {terminal_name}&&screen -x -S {terminal_name} -p 0 -X stuff "{launch_command}&&exit\n"
   • Windows cd "{launch_path}"&&start cmd.exe cmd /C python -c "import os;os.system('title {terminal_name}');os.system('{launch_command}')"

Note: Under Linux system, the plugin can close the mirror server through the screen. Under Windows system, you must set MCSM or RCON to close the mirror server through the plugin.

enable bool

• Whether to enable the terminal. when MCSM is not enabled and this option is true, the mirror server will be started through the terminal.

launch_path str

• The path where the startup command is executed, usually the directory where the mirror server is located.

launch_command str

• The startup command that needs to be executed, if a simple startup command cannot meet your requirements, you can create a .bat (or .sh) file and write the startup command in it, and then execute the file.

port int

• The port on which the mirror server runs, the plugin will check the running status of the mirror server by checking the port status.

terminal_name str

• The title of the new terminal or the name of the new screen, which is convenient for the operation and maintenance of the mirror server.

regex_strict bool

• Whether to continue to verify if the process name must be java.exe after finding the port when checking the running status of the mirror server. Generally, there is no need to turn it on. If different processes may run on the same port at different times, for example, during a certain period, Minecraft runs on port port, and during another period, another program runs on port port while Minecraft is not running, then to a certain extent this option can avoid misjudging other processes as java processes.

system str

• System type, if it is null, the system type will be automatically obtained. Optional: Linux Windows (the first letter should be capitalized)

rcon: RCON Configuration

"rcon": {
    "enable": false,
    "address": null,
    "port": null,
    "password": null
}

enable bool

• Whether to enable RCON. When MCSM is not enabled, the plugin will execute the stop command and obtain the status of the mirror server through RCON. If both RCON and the terminal are enabled at the same time, the plugin will first check the status of RCON to obtain the status of the mirror server. If RCON is not connected, it will check the status through the port. If the status of RCON does not match the status of the port, a prompt will be given.

address str

• The connection address of RCON, does not include the port.

port int

• The connection port of RCON

password str

• The connection password of RCON

sync: Configuration file related to file synchronization

"sync": {
    "world": [
	"world"
    ],
    "source": "./server",
    "target": [
        "./Mirror/server"
    ],
    "ignore_inexistent_target_path": false,
    "concurrency": 4,
    "ignore_files": [
        "session.lock"
    ]
}

In sync, ./ refers to the MCDReforged root directory where the server is located.

mcdr_root (./)
 ├─ config
 ├─ logs
 ├─ plugins
 ├─ server (./server)
 |   └─ world
 └─ Mirror
     └─ server (./Mirror/server)
         └─ world

world list

• The directory that needs to be synchronized, it needs to be added when there are multiple world files in the archive.

source str

• The source server directory, which should usually be the working directory of MCDR, that is, the default server directory. Files are synchronized from source/world to target/world

target str, list

• The target server directory, you can only write a string if there is only one directory, and a list is needed for multiple directories. A copy of the source directory files will be synchronized for each target directory. By default, the MCDR working directory of the mirror server is located in the Mirror directory under the current MCDR root directory.

ignore_inexistent_target_path bool

• If a target server directory does not exist, it will be skipped when set to false. When set to true, the directory will be created and synchronization will continue.

concurrency int

• The number of threads performing hash calculations during synchronization.

ignore_files list

• Files that are not synchronized, if you use the carpet mod and the plus-carpet-addition(PCA) mod, it is recommended to add "carpet.conf" "pca.conf"

command: Command Configuration

"command": {
    "permission": {/* Command permission configuration */},
    "action": {/* Command behavior configuration */}
}

permission: Command Permission Configuration

"permission": {
    "status": 0,
    "start": 0,
    "stop": 2,
    "kill": 3,
    "sync": 2,
    "confirm": 0,
    "abort": 0
}

int

• The minimum MCDR permission level required to execute each command

action: Command Behavior Configuration

"action": {
    "status": {
        "require_confirm": false
    },
    "start": {
        "require_confirm": false
    },
    "stop": {
        "require_confirm": true
    },
    "kill": {
        "require_confirm": true
    },
    "sync": {
        "ensure_server_closed": true,
        "auto_server_restart": false,
        "check_status_interval": 5,
        "max_attempt_times": 3,
        "save_world": {/* Save world configuration */},
        "require_confirm": true
    },
    "confirm": {
        "timeout": 30,
        "cancel_anymsg": true
    },
    "abort": {
        "operator": "everyone"
    }
}

General Configuration

require_confirm bool

• When this option is true, the command !!mirror confirm needs to be entered to confirm the operation after executing the command

sync Configuration

ensure_server_closed bool

• When this option is true, synchronization will check whether the mirror server has stopped. When this option is false, synchronization will be carried out directly regardless of whether the mirror server has stopped or not.

auto_server_restart bool

• This option only takes effect when ensure_server_closed is true. When this option is true, if the mirror server is not stopped during synchronization, it will attempt to automatically stop the mirror server, perform synchronization, and automatically restart the mirror server after the synchronization is completed.

check_status_interval int

• This option only takes effect when auto_server_restart is in effect. After stopping the mirror server during synchronization, the plugin needs to confirm whether the mirror server has stopped. This option is the time interval for checking the status of the mirror server.

max_attempt_times int

• This option only takes effect when auto_server_restart is in effect. The number of attempts to check the status of the mirror server, after exceeding this number of attempts, it will no longer attempt to check the status of the mirror server, and output automatic shutdown failed and the current status information of the mirror server. Equivalent to the timeout time timeout = check_status_interval * max_attempt_times

save_world Save world configuration Generally no need to change

"save_world": {
    "turn_off_auto_save": true,
    "commands": {
        "save_all_worlds": "save-all flush",
        "auto_save_off": "save-off",
        "auto_save_on": "save-on"
    },
    "saved_world_regex": "^Saved the game$",
    "save_world_max_wait_sec": 60
}

turn_off_auto_save bool

• Turn off auto save when saving the world

commands Related commands

• save_all_worlds str
  • Command to save the world
• auto_save_off str
  • Command to turn off auto save
• auto_save_on str
  • Command to turn on auto save

saved_world_regex str

• Regular expression to match the server "world saved" log

save_world_max_wait_sec int

• The maximum waiting time (seconds) for saving the world. After the timeout it will skip saving the world and perform synchronization

confirm Configuration

Players can only confirm the commands they have executed

timeout int

• Command that needs confirmation will be canceled after the number of seconds. If the player has not taken any action after executing a command, the command will be canceled automatically.

cancel_anymsg bool

• If the player sends a message other than the confirm command after executing a command, the command operation will be canceled automatically. In addition, if the player executes another command corresponding to the mirror server after executing a command, the previously executed command will be canceled too.

abort Configuration

This feature is still under development

display: Display Configuration

"display": {
    "server_name": "Mirror"
}

server_name str

• The name of the "mirror server", used to distinguish between different mirror servers in the display

Example of Multi-mirror Server Configuration File

{
    "!!mirror": {
        "mcsm": {
            "enable": true,
            "url": "http://127.0.0.1:23333/",
            "uuid": "71154??????????0a1a2f4dd90695609",
            "remote_uuid": "6e927??????????999f0e66bc404071b",
            "apikey": "b8f???????????????????????????ade"
        },
        "terminal": {
            "enable": false,
            "launch_path": "./Mirror",
            "launch_command": "python -m mcdreforged",
            "port": null,
            "terminal_name": "Mirror",
            "regex_strict": false,
            "system": null
        },
        "rcon": {
            "enable": false,
            "address": null,
            "port": null,
            "password": null
        },
        "sync": {
            "world": [
                "world"
            ],
            "source": "./server",
            "target": [
                "./Mirror/server"
            ],
            "ignore_inexistent_target_path": false,
            "concurrency": 4,
            "ignore_files": [
                "session.lock"
            ]
        },
        "command": {
            "permission": {
                "status": 0,
                "start": 0,
                "stop": 2,
                "kill": 3,
                "sync": 2,
                "confirm": 0,
                "abort": 0
            },
            "action": {
                "status": {
                    "require_confirm": false
                },
                "start": {
                    "require_confirm": false
                },
                "stop": {
                    "require_confirm": true
                },
                "kill": {
                    "require_confirm": true
                },
                "sync": {
                    "ensure_server_closed": true,
                    "auto_server_restart": true,
                    "check_status_interval": 5,
                    "max_attempt_times": 3,
                    "save_world": {
                        "turn_off_auto_save": true,
                        "commands": {
                            "save_all_worlds": "save-all flush",
                            "auto_save_off": "save-off",
                            "auto_save_on": "save-on"
                        },
                        "saved_world_regex": "^Saved the game$",
                        "save_world_max_wait_sec": 60
                    },
                    "require_confirm": true
                },
                "confirm": {
                    "timeout": 30,
                    "cancel_anymsg": true
                },
                "abort": {
                    "operator": "everyone"
                }
            }
        },
        "display": {
            "server_name": "Mirror"
        }
    },
    "!!mirror2": {
        "mcsm": {
            "uuid": "83011??????????49c1133fc08a41b80"
        },
        "sync": {
            "target": [
                "./Mirror2/server"
            ]
        },
        "display": {
            "server_name": "Mirror2"
        }
    },
    "!!mirror3": {
        "mcsm": {
            "enable": false
        },
        "sync": {
            "target": [
                "./Mirror3/server"
            ]
        },
        "terminal": {
            "enable": true,
            "launch_path": "./Mirror3",
            "port": 30002,
            "terminal_name": "Mirror3"
        },
        "rcon": {
            "enable": true,
            "address": "127.0.0.1",
            "port": 31002,
            "password": "p@ssw0rd"
        }
    }
}

Acknowledgements

• Hash comparison idea / better_backup
• Configuration file permission configuration idea / PrimeBackup
• Save world idea / QuickBackupM

ToDo

• Command execution confirmation
• Command execution delay
• Prohibit synchronization !!mirror sync enable/disable reason
• language file
• Command disable
• RCON support
• Start server through command line without MCSM
• Linux/Windows execute kill command through terminal
• Display history synchronization records