From adf72b6bc47ed2ef6d6faae886a19b2d86b93dca Mon Sep 17 00:00:00 2001 From: CyberFox Hax Date: Tue, 25 May 2021 15:51:02 +0800 Subject: fixing and adding documentation for RemoteAccess (#489) * Update Remote-Access.md Some of the descriptions didn't adequately explain how Soap worked outside of php. So i've rephrased to focus more on general HTTP. Also the in XML payload i needed to change TC to AC. I've also included examples of responses as well as a NodeJS function. * Update sidebar.html adding remote access into the sidebar * Update Remote-Access.md using proper code blocks * Update final-server-steps.md adding link to remote access documentation * Update Remote-Access.md changing java script var to const --- docs/Remote-Access.md | 168 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 140 insertions(+), 28 deletions(-) (limited to 'docs/Remote-Access.md') diff --git a/docs/Remote-Access.md b/docs/Remote-Access.md index f22fc52..a1651db 100644 --- a/docs/Remote-Access.md +++ b/docs/Remote-Access.md @@ -52,35 +52,147 @@ In a more simplified format: SOAP for websites, telnet for command line. Due to it's ubiquity telnet is easy to use from almost anywhere. -1. open up a terminal session (or PuTTY) and type in `telnet {{ ip }} {{port}}` +1. open up a terminal session (or PuTTY) and type in `telnet localhost 3443` 2. Enter your username and password. #### Soap -Soap works using POST requests on the HTTP protocol. If you are using php for your server, these is a module that will create and send SOAPs for you, namely: - - $conn = new SoapClient(NULL, array( - 'location' => "http://{{ ip }}:{{ port }}/", - 'uri' => 'urn:TC', - 'style' => SOAP_RPC, - 'login' => '{{ username }}', - 'password' => '{{ password }}' - )); - echo $conn->executeCommand(new SoapParam('server info', 'command')); - -However if you are not using php, it's a little more complicated. Or, it was before this documentation showed up! To create a valid soap request you need to include the appropriate xml namespaces. These were taken directly from the ones the server itself uses. You can see the SOAP itself is taken from the SOAP-ENV schema. Under the ns1 namespace are the commands we need to interact with the server. All commands go in the body of the SOAP. To send a command, you call the function executeCommand in the ns1 namespace and send the parameter command to the server. In this case our command gets the server status. - - - - - server status - - - - -The response to this command is what you would expect from the terminal. +Soap works using standard HTTP POST. The entire post payload is XML. + +```xml + + + + server status + + + +``` + +The response will look like this: + +```xml + + + + + AzerothCore rev. 6f4f0043c2ab+ 2021-05-18 02:16:59 +0200 (master branch) (Win64, RelWithDebInfo) +Connected players: 0. Characters in world: 0. +Connection peak: 0. +Server uptime: 5 second(s). +Update time diff: 10ms, average: 10ms. + + + + +``` + +Error response looks like this + +```xml + + + + + SOAP-ENV:Client + Error 401: HTTP 401 Unauthorized + + + +``` + +You need to authenticate by putting the username and password in the URI like this: `http://soapuser:abcd1234@localhost:7878/` (this is also known as "basic auth") + +setting request header `Content-Type: application/xml` is not needed. For now. + +## Code Examples + +
+ PHP + +using built-in [SoapClient](https://www.php.net/manual/en/class.soapclient.php) + +```php +$conn = new SoapClient(NULL, array( +'location' => "http://{{ ip }}:{{ port }}/", +'uri' => 'urn:AC', +'style' => SOAP_RPC, +'login' => 'soapuser', +'password' => 'abcd1234' +)); +echo $conn->executeCommand(new SoapParam('server info', 'command')); +``` + +
+
+ NodeJS (TypeScript) + +using [xml2js](https://www.npmjs.com/package/xml2js) to parse the response. Please make sure to sanitize the inputs. + +```typescript +function AzerothCore_Soap(command){ + return new Promise((resolve, reject)=>{ + const req = http.request({ + port: 7878, + method: "POST", + hostname: "localhost", + auth: "soapuser:abcd1234", + headers: { 'Content-Type': 'application/xml' } + }, res=>{ + res.on('data', async d => { + const xml = await xml2js.parseStringPromise(d.toString()); + + const body = xml["SOAP-ENV:Envelope"]["SOAP-ENV:Body"][0]; + const fault = body["SOAP-ENV:Fault"]; + if(fault){ + resolve({ + faultCode : fault[0]["faultcode"][0], + faultString: fault[0]["faultstring"][0], + }); + return; + } + const response = body["ns1:executeCommandResponse"]; + if(response){ + resolve({ + result: response[0]["result"][0] + }); + return; + } + console.log(d.toString()); + }) + }); + req.write( + '' + + '' + + '' + + ''+command+'' + + '' + + '' + + '' + ); + req.end(); + }); +} +``` + +
-- cgit